vtcode-core

Root AGENTS.md | Largest crate (~70 modules). Agent loop, tools, LLM, config, safety, UI.

Key Modules

core/agent/ runtime | llm/ thin re-export layer + models_manager/ + factory.rs + cgp.rs | tools/ + tool_policy.rs registry | safety/ + sandboxing/ + exec_policy/ + command_safety/ policies | config/ + constants.rs | context/ + memory/ conversation | prompts/ | exec/events.rs (re-exports vtcode-exec-events::ThreadEvent) | git/ worktree management | loop_memory.rs + loop_state.rs loop persistence | tools/web_search/ | tools/defuddle/ | tools/outline_search/

Rules

• Re-export from lib.rs. Consumers must not reach into submodules.
• ThreadEvent lives in vtcode-exec-events — never duplicate.
• exec_policy (Codex policy) != command_safety (tree-sitter validation) — do not merge.
• Constants in config::constants, not inline.
• Feature gates at module level, not scattered #[cfg].

Adding a Tool

Implement in tools/ (web_search, defuddle, outline_search are reference patterns) → register in tools::registry → name in tools::names → classify in ToolPolicy → wire in core/agent/.

Adding an LLM Provider

Implement in vtcode-llm/src/providers/ (the canonical home). Use adding-llm-providers skill. Update ModelId::all_models() + builtin_model_presets(). Then add a re-export in vtcode-core/src/llm/providers/mod.rs.

Gotchas

• retry.rs re-exports vtcode_commons::retry::RetryPolicy; domain methods (typed downcasts, run_with_retry) live on the RetryPolicyCoreExt extension trait — import it for method syntax.
• Error classification is vtcode_commons::classify_anyhow_error → ErrorCategory; UnifiedErrorKind/ToolErrorType are derived views and ToolExecutionError.error_type always derives from category.
• lib.rs is 500+ lines — append re-exports, don't restructure.
• #[cfg_attr(not(test), allow(...))] clippy suppressions — do not remove.
• Provider implementations live in vtcode-llm/src/providers/, not in core. Core's llm/providers/ is a re-export facade.