CtxLayer - Context Layer for AI agents

Intention

Project – Context organization unit. A project can span one or more Git repositories.
Task – One task within that project. Think of a task like a Git branch: create a new task whenever you start a feature, refactor, or research spike.
Inside each task you get:
- data/ – All data the agent can use (reference material, repos, sample data).
- docs/ – Documentation. Whenever something meaningful is done – research, an implementation plan, or the implementation itself – that knowledge is written into the task's docs/ folder using the naming convention.
In later iterations, the relevant Markdown in docs/ and the contents of data/ are available so the agent can narrow its focus and work more precisely.

What it does

Manages a global store at ~/.agents/ctxlayer/projects/ where projects and tasks live.
Each task has docs/ and data/ for documentation and reference material.
A local .ctxlayer/config.yaml in your repo (or workspace) tracks the active project and task.
An agent skill teaches AI coding assistants (Cursor, Claude Code, etc.) how to write documentation and manage context using these conventions.

Directory layout

~/.agents/ctxlayer/                              # global store (in home dir)
  projects/
    <project-name>/                       # one per project (can span one or more git repos)
      <task-name>/                        # one per task (think: branch)
        docs/                             # documentation (01-name.md, 02-name.md, ...)
        data/                             # reference material, git submodules, sample data

<your-repo>/
  .ctxlayer/                              # local config (gitignored)
    config.yaml                           # active-project and active-task
    <task-name> -> symlink               # symlink to the task folder in global store

Installing the CLI

From this repo (local development)

cd /path/to/context-layer
npm install
npm link

After that, ctx is available globally on your machine. Edits to bin/cli.js take effect immediately.

Uninstalling

npm unlink -g ctx

CLI commands

Command	Description
`ctx`	Show help and available commands
`ctx new [name]`	Create a new task (initializes workspace, prompts for project if needed)
`ctx import`	Import a task from any project as a local symlink
`ctx git [args...]`	Run git in the current task directory
`ctx drop task [name]`	Remove a task symlink (with optional task name)
`ctx drop project [name]`	Remove a project directory from local `.ctxlayer/` (optional project name)
`ctx delete task`	Delete a task from the context store and remove its symlink
`ctx delete project`	Delete a project from the context store and remove its local directory
`ctx status`	Show the current active project and task
`ctx set`	Set active project and task (prompts to select)

Config file

Located at .ctxlayer/config.yaml in your repo:

active-project: my-project
active-task: my-task

Installing the agent skill

The repo includes an agent skill at skills/ctxlayer/SKILL.md that teaches AI coding assistants (Cursor, Claude Code, etc.) how to use the ctx CLI, write documentation in the correct format, and manage context.

Local install via npx skills

Use npx skills to install from the local repo:

npx skills add /path/to/context-layer -g -a cursor --skill ctxlayer -y

What the skill teaches the agent

CLI commands – how to use ctx new, ctx status, ctx set, etc.
Docs convention – when something meaningful is done (research, plan, implementation), create numbered markdown files (01-name.md, 02-name.md) in the active task's docs/ folder so later iterations can use that documentation.
Data convention – reference material goes in the task's data/ folder (repos as git submodules). This is the data the agent uses to focus its work.

License

Apache-2.0. See LICENSE for the full text.