ctx — durable context for coding agents

ctx creates a small, reviewable context system inside a Git repository. Its default team mode keeps durable project facts available to share while isolating clone/session state:

• core fact documents live under .ctx/context/;
• .ctx/local/CONTINUE.md records current local state and stays ignored;
• INDEX.md routes an agent to only the documents a task needs;
• behavior and glossary add-ons are selected by default; other add-ons stay opt-in;
• ctx never stages or commits files.

Use --mode local when the entire context folder should remain private through the repository's common .git/info/exclude file.

Folder-first layout v3

A default new initialization creates the fixed core plus behavior and glossary:

.ctx/
├── .gitignore
├── config.json
├── README.md
├── INDEX.md
├── context/
│   ├── overview/
│   │   └── index.md
│   ├── architecture/
│   │   └── index.md
│   ├── caveats/
│   │   └── index.md
│   ├── behavior/         # default-selected add-on
│   │   └── index.md
│   └── glossary/         # default-selected add-on
│       └── index.md
└── local/
    └── CONTINUE.md

Each concern has one owner: overview owns purpose and scope; behavior owns business/domain rules, decisions, state transitions, and expected outcomes; architecture owns components, implementation flows, and technical invariants; caveats owns confirmed limitations and operational gotchas; continuation owns current local state only. Each category starts with a concise summary and routes. During population, give independently useful explanations sibling topic files from the start; keep short, related facts together. Folders provide room to grow without generating empty topic stubs or forcing one file per term.

The core stays fixed and lean. Behavior and glossary remain add-ons, but new scaffolds select them by default. The index routes logic-related tasks to behavior and terminology-related tasks to glossary. Omit either with --without behavior or --without glossary; use --without behavior,glossary for a core-only scaffold. The other add-ons remain opt-in.

Add-on	Installed file	Default	Use when
behavior	context/behavior/index.md	Yes	Core business/domain rules and expected outcomes need explanation
glossary	context/glossary/index.md	Yes	Project-specific terminology needs disambiguation
operating	OPERATING.md	No	The owner wants a shared project-specific working agreement
contracts	context/contracts/index.md	No	Data, API, storage, or message compatibility is a real boundary
extending	context/extending/index.md	No	The project has supported extension points
review	workflows/review.md	No	The project wants a shared, tool-neutral review profile

See Folder-first layout v3 for metadata, routing, managed markers, and size guidance.

Install

npm install -g @neuvybe/ctx
ctx --version

Or install with Go:

go install github.com/neuvybe/ctx/cmd/ctx@latest

Initialize and extend

# Default: team mode with the v3 core plus behavior and glossary
ctx init /path/to/repo

# Core only: omit both default-selected add-ons
ctx init /path/to/repo --without behavior,glossary

# Entire scaffold private to the repository
ctx init /path/to/repo --mode local

# Select other add-ons at creation; --with is repeatable and comma-friendly
ctx init /path/to/repo --with operating,contracts

# Inspect the catalog, then add one capability later
ctx add --list
ctx add /path/to/repo review

# Adopt behavior in an existing v2 scaffold after upgrading ctx
ctx update /path/to/repo
ctx add /path/to/repo behavior

# One custom top-level folder name
ctx init /path/to/repo --folder .agent

For a new initialization, --folder accepts one top-level directory name made of letters, digits, ., _, or -. Nested paths and spaces are not part of the new-layout CLI contract.

On a fresh clone containing committed team context, run ctx init again and repeat --folder when customized. It hydrates the missing ignored continuation without rewriting durable files.

ctx generates the behavior category index, context/behavior/index.md. Keep it as a short model. During context filling, the developer or agent can create context/behavior/<topic>.md for detailed workflow or domain rules and link each child from the parent. These project-specific topics are not generated by ctx. Label implemented behavior separately from intended changes and cite the relevant source, tests, or canonical requirements. Existing scaffolds keep their configured add-ons; update and hydration do not install new defaults.

Fill and maintain context

ctx includes a portable ctx skill using the open Agent Skills format, with optional OpenAI-specific metadata. Agents can use this separately installed bundle for population, task routing, evidence reconciliation, and local handoffs. See activation and the booking demo; CLI initialization does not install or automatically activate a skill.

Project-fact documents carry one machine-readable metadata line:

<!-- ctx:doc {"status":"draft","verifiedAt":"","sources":[]} -->

Set status to verified only after checking the recorded source paths, using <commit-hash> @ YYYY-MM-DD (git rev-parse HEAD) as the immutable verification point. Use not-applicable deliberately rather than filling an irrelevant document with boilerplate. draft facts are leads to verify, not authority.

For consequential new or changed guarantees, use the recommended maintainer checkpoint. Verified metadata records scoped evidence checking, not human approval.

Use the checks for their distinct purposes:

• ctx doctor [target] [--folder .ctx] validates scaffold structure, layout compatibility, managed-marker grammar, and Git visibility/privacy boundaries.
• ctx status [target] [--folder .ctx] summarizes document readiness, flags listed sources changed since their recorded commit, and emits non-failing size guidance. It does not verify factual truth or source sufficiency.

The normal maintenance flow is:

ctx update /path/to/repo
ctx doctor /path/to/repo
ctx status /path/to/repo
git status --short .ctx

In team mode, a human reviews and chooses whether to stage durable changes; local/ remains ignored. In local mode, the whole selected folder remains ignored. See the fill-context workflow.

For a complete populated scaffold and a walkthrough from initialization through source changes and fresh-clone handoff, explore the worked example using ctx itself. That example is a pinned layout-v2 snapshot, not the new default. It separates generated structure, authored facts, and local session state.

Commands

• ctx init [target] [--folder .ctx] [--mode team|local] [--with <addons>] [--without <addons>]
• ctx add [target] <addon...> [--folder .ctx]
• ctx add --list
• ctx update [target] [--folder .ctx]
• ctx doctor [target] [--folder .ctx]
• ctx status [target] [--folder .ctx]
• ctx upgrade
• ctx --version

Existing scaffold compatibility

Existing layout-v2 scaffolds keep their flat context/<category>.md paths, selected add-ons, and template revision 2.0.1. Update, add, status, doctor, and team hydration continue to use the saved layout; no implicit file moves occur. There is no conversion command yet. See layout compatibility.

Existing schema-v1 and config-less legacy scaffolds are not silently converted to a newer layout. Their file names, unnamed ordinal managed blocks, update source, and continuation location remain on the v1 compatibility path. Config-less legacy scaffolds stay whole-folder local with root CONTINUE.md.

The deprecated Go Init(repo, folder) compatibility wrapper likewise emits the legacy v1 layout and preserves safe repository-contained custom paths accepted by ctx 0.1. New Go integrations should use the current options-based API.

See the 0.2 migration guide for the team-mode default and legacy visibility behavior. See the layout-v2 migration guide for the lean core, add-ons, readiness metadata, and Go API notes.

Design principles

The short version is: share durable evidence, keep state local, load context hierarchically, defer to owner instructions, and distinguish structural health from factual readiness. The full rationale is in Principles.

Development

make build
make test
make smoke

Release automation ships GitHub binaries and the @neuvybe/ctx npm launcher. The platform supplies structure and lifecycle checks; an agent still has to read the actual repository and write accurate context.