AGENTS.md

June 28, 2026 · View on GitHub

Keep this file concise and under 150 lines. Root guidance belongs here; detailed explanations belong in docs/, skills, .vtcode/memory/, or crate-local AGENTS.md files.

Rules

Conventional Commits (type(scope): subject).
4-space indentation, snake_case fns, PascalCase types, anyhow::Result<T> + .with_context().
CI sets RUSTFLAGS: "-D warnings" and uses --locked. Match locally with cargo check --locked when relevant.
Keep changes surgical. Preserve existing APIs unless the task requires a change.
vtcode-exec-events::ThreadEvent is the authoritative runtime event contract — do not invent parallel types.
Harness config is split across agent.harness, automation.full_auto, context.dynamic — do not add a new top-level harness subsystem.
Prefer compact_str::CompactString (aliased as CompactStr in vtcode_core::types) over String for small string fields. Use Cow<'static, str> for mostly-static return strings.
Shape-suffix naming: encode the dimensional structure of data in variable/type names. For feature vectors, document a dimension key (table of index → name → meaning). For bare tuples holding structured data, promote to named structs so the shape is explicit in the type system (inspired by Noam Shazeer's shape-suffix convention).
clippy.toml allows unwrap/panic/indexing in tests only.
Dev profile has incremental = false (sccache). Set CARGO_INCREMENTAL=1 to override.
Every new major feature must update docs: user-facing behavior → docs/development/ guide + a table row/section in the relevant quick-reference; agent-facing tool surface → prompt guidance (vtcode-core/src/prompts/guidelines.rs) + schema (vtcode-utility-tool-specs); runtime contract → vtcode-exec-events::ThreadEvent. No feature is "done" until the docs it changes are updated and the AGENTS.md detailed-guides links still resolve.

Detailed Guides

Development overview and setup: docs/development/README.md, docs/development/DEVELOPMENT_SETUP.md.
Testing: docs/development/testing.md, docs/guides/pty-integration-testing.md.
CI/release: docs/development/ci-cd.md, docs/development/CHANGELOG_GENERATION.md.
Architecture/conventions: docs/guides/code-organization-patterns.md, docs/guides/async-architecture.md, docs/development/rust-performance-principles.md.
Tools/security: docs/development/grep-tool-guide.md, docs/development/grep-quick-reference.md, docs/development/COMMAND_SECURITY_MODEL.md, docs/guides/security.md.
Harness/agent behavior: docs/guides/agent-loop-contract.md, docs/harness/INDEX.md, docs/harness/CORE_BELIEFS.md, docs/harness/ARCHITECTURAL_INVARIANTS.md, docs/harness/AGENT_LEGIBILITY_GUIDE.md.
Planning and automation: docs/guides/planning-workflow.md, docs/guides/full-automation.md, docs/development/EXECUTION_POLICY.md.
Loop engineering: docs/project/PLAN-loop-engineering.md — worktree isolation, propose/verify sub-agents, loop state persistence, cost guardrails.
Models/providers: docs/development/ADDING_MODELS.md, docs/development/MODEL_ADDITION_WORKFLOW.md, docs/development/MODEL_ADDITION_CHECKLIST.md.

Workspace

Cargo workspace, ~30 crates. Rust stable, MSRV 1.88, edition 2024. default-members = root, vtcode-core, vtcode-ui only.

Crate	Role
`vtcode` (root `src/`)	Binary, CLI, session bootstrap
`vtcode-core`	Agent loop, tools, prompts, LLM orchestration, UI
`vtcode-ui`	Unified UI: design system, theme registry, TUI framework
`vtcode-config`	Config loading and schema
`vtcode-bash-runner`	Shell execution sandbox
`vtcode-acp`	Agent Client Protocol (Zed)
`vtcode-auth`	OAuth and credential storage
`vtcode-indexer`	Code indexing and search
`vtcode-exec-events`	`ThreadEvent` contract and ATIF export
`vtcode-commons`	Shared utilities
`vtcode-macros`	Procedural macros
`vtcode-utility-tool-specs`	JSON schemas for utility, file, and collaboration/HITL tools
`vtcode-llm`	LLM provider abstraction, client implementations, streaming (partial extraction)
`vtcode-skills`	Skill types, discovery, loading, and validation (partial extraction)
`vtcode-safety`	Command safety detection, execution policies, sandboxing
`vtcode-a2a`	Agent2Agent (A2A) protocol client and server
`vtcode-mcp`	Model Context Protocol client, connection pooling, tool discovery
`xtask`	Release packaging automation

New reusable logic: put it in an existing small crate or a new one. Keep it out of vtcode-core by default unless tightly coupled to the core runtime.

Per-Module Guidance

Every crate has its own AGENTS.md with crate-specific conventions:

Crate	AGENTS.md
`vtcode` (binary)	src/AGENTS.md
`vtcode-core`	vtcode-core/AGENTS.md
`vtcode-ui`	vtcode-ui/AGENTS.md
`vtcode-config`	vtcode-config/AGENTS.md
`vtcode-bash-runner`	vtcode-bash-runner/AGENTS.md
`vtcode-acp`	vtcode-acp/AGENTS.md
`vtcode-auth`	vtcode-auth/AGENTS.md
`vtcode-indexer`	vtcode-indexer/AGENTS.md
`vtcode-exec-events`	vtcode-exec-events/AGENTS.md
`vtcode-commons`	vtcode-commons/AGENTS.md
`vtcode-macros`	vtcode-macros/AGENTS.md
`vtcode-utility-tool-specs`	vtcode-utility-tool-specs/AGENTS.md
`vtcode-llm`	vtcode-llm/AGENTS.md
`vtcode-skills`	vtcode-skills/AGENTS.md
`vtcode-safety`	vtcode-safety/AGENTS.md
`vtcode-a2a`	vtcode-a2a/AGENTS.md
`vtcode-mcp`	vtcode-mcp/AGENTS.md
`xtask`	xtask/AGENTS.md

After significant changes (new modules, convention shifts, discovered gotchas, public API changes), use the audit-module-agents skill to check if the affected crate's AGENTS.md needs updating. Keep each local AGENTS.md under 30 lines.

Project Memory

Session-independent knowledge lives in .vtcode/memory/ (gitignored): gotchas.md, issues.md, library.md, decisions.md, and scratch.md. Read these files when context is needed. Write durable learnings there. See .vtcode/memory/README.md for format rules.

Build & Verification

Prefer ./scripts/check-dev.sh (10-30s) over ./scripts/check.sh (2-5m) for iteration.

Change	Command
Fast gate	`./scripts/check-dev.sh`
+ tests	`./scripts/check-dev.sh --test`
+ workspace	`./scripts/check-dev.sh --workspace`
+ lints	`./scripts/check-dev.sh --lints`
Harness PTY/TUI	`./scripts/check.sh harness`
Release/PR	`./scripts/check.sh`
Ast-grep rules	`vtcode check ast-grep`
Ast-grep scan	`ast-grep scan` (requires `sgconfig.yml` + `rules/`)

Narrow commands: cargo check, cargo nextest run, cargo fmt, cargo clippy.

Testing

Runner: cargo nextest run (parallel, fast). Fallback: cargo test --workspace.
Single test: cargo nextest run test_name or cargo test test_name.
Single crate: cargo nextest run -p vtcode-core.
Profiles: default (local), ci (no fail-fast, 2 retries, 60s timeout), quick (TDD, skips integration/e2e).
Harness regressions: cargo test -p vtcode-core --test pty_tests; cargo test -p vtcode-bash-runner --test pipe_tests; cargo test -p vtcode --bin vtcode inline_events::tests.
Integration tests: tests/ at workspace root. Unit tests: in-module.

Skills & Special Workflows

Skills are invoked via the Skill tool; subagents are spawned via the Agent tool. Project slash commands live in .claude/commands/; agents live in .claude/agents/.
LLM providers: use the adding-llm-providers skill. The /model picker uses ModelId::all_models(); builtin_model_presets() is used by ModelsManager. Both may need updates.
New workspace crates: use the adding-workspace-crate skill. This affects more than Cargo.toml; all workspace path dependencies need version fields.
Structural code work: prefer ast-grep over text grep for code shape, calls, impls, and codemods. Use rg for prose, logs, and config strings. Always invoke ast-grep, not the sg alias. For token-efficient symbol maps, use action=outline in unified_search (wraps ast-grep outline, auto-installs if missing).
Cap large command output: COMMAND 2>&1 | head -c 4000.