Agent Guide
March 31, 2026 ยท View on GitHub
Use this file as the first pointer for coding agents and automation that need to work in or against this repo.
Pick The Right Surface
- Full autocontext control plane:
autocontext/ - Node/TypeScript toolkit and CLI:
ts/ - Interactive terminal UI:
ts/src/tui/ - External agent usage guide:
autocontext/docs/agent-integration.md
Working Directories
- Run Python commands from
autocontext/. - Run Node/TypeScript commands from
ts/. - Run TUI-related commands from
ts/.
Most repo-level commands in the READMEs assume one of those package directories as the current working directory.
Setup
Python:
cd autocontext
uv venv
source .venv/bin/activate
uv sync --group dev
TypeScript:
cd ts
npm install
Common Checks
Python:
cd autocontext
uv run ruff check src tests
uv run mypy src
uv run pytest
TypeScript:
cd ts
npm run lint
npm test
Public Docs To Keep In Sync
If you change public commands, environment variables, package names, or agent-facing workflows, update the relevant docs in the same change:
README.mddocs/README.mdautocontext/README.mdts/README.mdexamples/README.mdautocontext/docs/agent-integration.mdCONTRIBUTING.mdCHANGELOG.md
Key References
- Repo overview:
README.md - Docs overview:
docs/README.md - Contributor workflow:
CONTRIBUTING.md - Python package guide:
autocontext/README.md - TypeScript package guide:
ts/README.md - Copy-paste examples:
examples/README.md - External agent guide:
autocontext/docs/agent-integration.md
Intentional Deletions
- Before restoring deleted modules to make CI green, check whether
autocontext/src/still imports them. - If only tests are failing, prefer rewriting or deleting the tests instead of restoring removed modules.
- Treat importable module paths as compatibility surfaces until callers are rewired or the removal is explicitly accepted as breaking.