AutoCode

AutoCode is a TypeScript-based coding agent CLI for working inside real code repositories. It combines repository scanning, context retrieval, tool execution, permission checks, session persistence, verification planning, and a terminal UI into one local workflow.

The project is designed for inspectable and reproducible software-engineering tasks: the agent should read the relevant repository context, make bounded file changes, run explicit verification when possible, and save enough run evidence for later review.

Features

• Repository overview and retrieval based on files, paths, dependencies, and symbol-oriented signals.
• Headless one-shot task execution through auto-code run.
• Full-screen terminal interaction through auto-code or auto-code chat.
• Built-in coding tools for reading files, searching, patching, shell verification, repository context, dependency paths, symbol graphs, and impact checks.
• Permission modes for write and shell operations.
• Verification modes for automatic, required, or disabled verification.
• Session persistence, task reports, change ledger, undo/redo support in the terminal UI, and replay-oriented report rendering.
• Experimental multi-stage agent modes for sequential multi-agent and graph runtime workflows.

Repository Layout

src/
  adapters/model/   Model provider adapters and environment resolution
  context/          Task-context assembly and compaction
  core/             Agent loop, prompt protocol, parser and recovery logic
  repo/             Repository scanning, dependency extraction and symbols
  retrieval/        Query-driven repository retrieval and ranking
  runtime/          CLI runtime, permissions, sessions, TUI and reports
  tools/            Built-in tool implementations
  index.ts          CLI entry point

examples/
  demo-workspace/   Small reproducible workspace for local smoke tests

scripts/
  swebench_eval/    Optional SWE-bench helper scripts
  swebench_wrapper/ Optional SWE-bench wrapper utilities

For a deeper module overview, see docs/architecture.md.

Requirements

• Node.js 20 or newer is recommended.
• npm is required for dependency installation and scripts.
• PowerShell examples use npm.cmd on Windows to avoid execution-policy surprises.

Install

npm.cmd install
npm.cmd run build

Run the CLI from source:

npm.cmd run dev -- --help

Build and start the compiled CLI:

npm.cmd run build
node dist/index.js --help

Optionally link it locally:

npm.cmd run setup:local
auto-code --help

Model Configuration

AutoCode supports two provider modes:

• mock: deterministic local smoke-test provider; no API key is required.
• openai-compatible: any endpoint that follows the supported chat or responses-style request shape.

Never commit real credentials. Keep secrets in one of these ignored local files:

• .env.local
• .auto-code/local.env

Start from .env.example, then replace the placeholders locally. A minimal shell-based configuration looks like this:

$env:AUTO_CODE_PROVIDER = "openai-compatible"
$env:AUTO_CODE_API_KEY = "replace-with-your-key"
$env:AUTO_CODE_BASE_URL = "https://api.example.com/v1"
$env:AUTO_CODE_MODEL = "example-code-model"

Use the mock provider when you only need to verify the CLI path:

npm.cmd run dev -- chat --provider mock --cwd examples/demo-workspace

Print model-resolution diagnostics before startup:

npm.cmd run dev -- run "Inspect this repository" --cwd . --model-debug

Common Commands

Open the terminal UI:

npm.cmd run dev -- chat --cwd . --provider mock

Run a one-shot task:

npm.cmd run dev -- run "Inspect the project structure and summarize the main modules" --cwd . --provider mock

Render repository context for a query:

npm.cmd run dev -- context "CLI entry point and task execution flow" --cwd .

Generate a report from a saved session:

node dist/index.js report .auto-code/sessions/<session>.json --format markdown

Useful task options:

--approval <always|never|on-request>
--verify-mode <auto|required|off>
--agent-mode <single|multi|graph>
--focus-path <path>
--refresh-context
--max-steps <number>

Local Verification

Run the type check:

npm.cmd run check

Build the project:

npm.cmd run build

Run the demo smoke test after building:

npm.cmd run verify:demo-mvp-smoke

The demo workspace can seed and repair a small deterministic bug:

cd examples/demo-workspace
npm.cmd run seed-bug
npm.cmd test

Then run AutoCode against that workspace from the repository root.

Security Notes

• Do not commit .env, .env.local, .auto-code/, generated sessions, build output, package archives, local evaluation workspaces, or API keys.
• .auto-code/ may contain local sessions, prompts, traces, model-resolution details, and credentials if you choose to store local.env there.
• If a real key was ever written to a file that might have been shared, revoke and rotate it from the provider console; deleting it locally is not enough.
• Review task reports before sharing them, because they can include prompts, repository paths, command output, and model diagnostics.

Before publishing the repository, verify that the upload only includes source and documentation files. In particular, keep these local-only paths out of the remote repository:

• node_modules/
• dist/
• .auto-code/
• .codegraph/
• .codex/
• .agents/
• .tmp-*
• acceptance-evidence/
• docs/generated/
• logs/
• reports/
• runs/
• tmp/
• wrapper-outputs/
• predictions/
• local SWE-bench workspaces, predictions, logs, and reports

The committed template file .env.example must contain only placeholder values. Real provider keys should stay in ignored local files or shell environment variables.

Development Notes

Keep code changes small and verify the narrowest relevant behavior first. For public examples and fixtures, use neutral placeholders such as https://api.example.com/v1, C:/example/project, and example__repo-123 instead of personal paths, private endpoints, or real credentials.