An open-source agentic-coding library. The body that powers AutoArchitect's Architect — usable on its own.
A Node.js / TypeScript library that provides the agent loop, tool dispatch, permission gating, budget tracking, and LLM provider adapters that any Claude-Code-class reasoner needs. Distributed as @autoarchitect/code on npm and aac as a CLI.
npm install @autoarchitect/code
# or
npx aac "summarize this codebase"Three integration surfaces:
- Library (the most common): import
query,Session,ToolRegistry,PermissionGate,makeProviderand compose them into your platform. - CLI (
aacstandalone binary): a personal coding agent over your current directory. - HTTP service (roadmap): a standalone server exposing the agent loop over HTTP/WS.
The AutoArchitect Studio platform uses this library as Architect's body — the same library, with different SOULs and different tools, can run a Devin-style coding agent, a research agent, an internal-tools assistant, anything in the Claude-Code-class space.
The agentic-coding primitives — the LLM loop, the tool dispatch, the permission gate, the budget tracker, the LLM provider adapters — have largely converged across the industry in 2025. Every team building an agentic platform reimplements the same shape: stream tool-use events, validate tool input with Zod, persist transcripts, compact at context-window limits, gate on approval for write operations.
autoarchitect-code packages that shape as an MIT-licensed library. The goal is simple: let platform builders focus on integration (workspace, kanban, deploy pipeline, sandbox) instead of reimplementing the agent loop.
import { query, Session, ToolRegistry, PermissionGate, makeProvider, readFileTool, writeFileTool, editFileTool, bashTool } from '@autoarchitect/code';
async function main() {
const llm = makeProvider({
provider: 'anthropic',
apiKey: process.env.ANTHROPIC_API_KEY,
model: 'claude-sonnet-4-5-20250929',
});
const tools = new ToolRegistry([readFileTool, writeFileTool, editFileTool, bashTool]);
const gate = new PermissionGate('auto');
const session = new Session({ cwd: process.cwd() });
const prompt = process.argv.slice(2).join(' ');
for await (const event of query({ prompt, session, tools, systemPrompt: 'You are a focused coding agent.', permissions: gate, llm })) {
if (event.type === 'assistant.chunk') process.stdout.write(event.text);
else if (event.type === 'tool.start') process.stdout.write(`\n[${event.name}] `);
else if (event.type === 'tool.end') process.stdout.write(`(${event.duration_ms}ms) `);
}
console.log('\n');
}
main().catch(console.error);That's the smallest useful host: 30 lines, gives you a personal coding agent over your current directory.
Seven primitives, each a real export with a stable type signature and tests:
query— the agent loop. An async-generator yieldingQueryEvents, returningQueryResult. Discriminated-union events:turn.start,assistant.chunk,tool.proposed,permission.ask,tool.start,tool.end,compact,turn.end,error.Session— in-memory conversation state plusBudgetTracker. Holds the message list, tracks tokens / turns / tool calls / wall time. Persistence is the host's choice; aac doesn't pick a database.ToolRegistry— name-indexed collection with Zod-validated input and explicit output strings. Each tool isTool<I>with name, description, JSON Schema, Zod schema, permission requirement, and acall(input, ctx)returning a string.PermissionGate— five-mode permission system:plan/default/allowlist/auto/bypass. Indefaultmode, write/danger tools require approval before executing.- LLM provider adapters —
AnthropicProvider,OpenAIProvider(Mistral / vLLM / Ollama / custom gateways viabaseUrl),MockLlmProviderfor tests. PlusmakeProvider({ provider, ... })convenience. - Built-in tools — file ops (
readFileTool,writeFileTool,editFileTool,globTool,grepTool,listDirTool), shell (bashTool), web (fetchUrlTool,webSearchTool), memory (memorySaveTooletc), meta (enterPlanModeTool,askUserQuestionTool,compactNowTool), skills (listSkillsTool,loadSkillToolwithFsCatalogReader). - Subsystems —
GapFiller(an 8-step loop that authors a new skill or archetype when a host platform's capability gap is detected), and theaacCLI.
The library is small and opinionated. The full architecture is documented in specs/ (00_overview.md is the entry point).
The decisions that distinguish aac from rolling your own:
Tools designed FOR LLMs, not given a raw shell. Following Princeton's SWE-agent ACI paper, the built-in tools have bounded views (default 100 lines for read_file), line-numbered output (so subsequent edits are precise), explicit success/error strings ((no output) when stdout is empty, ERROR: <code> with detail), command-history detection (the bash tool emits a hint when a command repeats with no intervening edit). Hosts can override; the defaults are opinionated.
Diff-based edits, never whole-file rewrite. editFileTool produces unified diffs via the standard diff package. Refuses string_not_unique and no_change cases. Hosts that want strict no-rewrites can drop writeFileTool from the registry. The library's edit primitive pushes toward iteration.
Termination is a typed tool call, not a string. query ends when the LLM emits finish_reason: 'stop', OR when the host registers a termination tool and the LLM calls it. There is no string-pattern check for "DONE" or "TERMINATE." AutoGen's documented multi-year struggle with string-pattern termination is one of the explicit reasons aac took this design.
Single-agent by design. No built-in "spawn another query." Hosts that want a subagent shape implement it on top — the way AutoArchitect Studio's SubagentHost does, with a hard 2-level tree rule. aac itself doesn't have a recursion path to enforce or break. (See Cognition's Don't Build Multi-Agents and the UC Berkeley MAST paper for why.)
Five permission modes, real audit shapes. plan (refuse-unsafe-tools-entirely), default (gate-on-approval), allowlist (explicit per-tool), auto (auto-approve), bypass (no gate — for hosts that sandbox the agent at the kernel level, like AutoArchitect's gVisor runtime).
Three things aac deliberately doesn't do — because we want the library to compose, not lock in choices:
- Storage: aac doesn't pick a database. The
Sessionis in-memory; persistence is the host's choice. - Streaming:
queryis an async-generator; the host decides what to do with the event stream (SSE, WebSocket, in-memory collection, log to disk). - Authentication: aac doesn't have user accounts. The host platform owns auth; aac's
PermissionGateis the in-loop authorization mechanism, not user identity.
These are deliberate. The library is a substrate, not a framework. Frameworks make decisions; substrates compose.
$ aac "review the last commit and write a one-paragraph summary"
$ aac --plan "ship a Stripe integration" # Plan mode — no code, just a plan
$ aac --tools=read_file,write_file,bash "fix the failing test in src/foo.test.ts"
$ aac --provider=openai --model=gpt-4o "summarize this codebase"The CLI is a thin wrapper around query with the same primitives. Permission modes, provider selection, tool subsetting, and Plan Mode are all flags.
@autoarchitect/code is at 0.1.0-spec as of the v60.0 AutoArchitect Studio reset. Pre-1.0 because we want to land Studio's v60 experiment first and stabilize aac's API based on what we observe. Once 1.0 ships (planned Q1 2027), the API is stable for at least 12 months on a major version line.
The roadmap to 1.0 is documented in specs/00_overview.md. Notable upcoming additions: HTTP service surface, native MCP server/client support, compaction policy controls, per-tool retry policies, stricter TypeScript types around tool input validation.
specs/00_overview.md— the architectural summary; start here.specs/02_query_engine.md— how the agent loop works.specs/03_tools.md— tool design guidance.specs/03_safety.md— safety invariants for the GapFiller subsystem.specs/07_session.md— Session + BudgetTracker contract.specs/11_llm_providers.md— provider adapter shape.
Examples (when populated) at examples/: a CLI coding agent, a documentation-summarizer agent, a research-with-citations agent. Each is under 200 lines and demonstrates one usage pattern.
The lineage of aac's design choices, made explicit:
- Agent-loop shape — Anthropic's Building Effective Agents and Claude Code's architecture.
- Tool-design philosophy — Princeton's SWE-agent ACI paper.
- Diff-based edit shape — Aider's unified diffs.
- Five-mode permission gate — Cursor's permission shape, Aider's auto-approve modes.
- No recursion primitive — Cognition's Don't Build Multi-Agents and the UC Berkeley MAST paper.
aac stands on the shoulders of all of these. The library exists because the industry's agentic-coding primitives have largely converged on a shape, and packaging that shape as an MIT library was a useful contribution to make.
Contributions welcome. Bug reports, feature requests, and integration questions go to GitHub issues. PRs against the spec set are reviewed with the same care as PRs against the code.
The mailing list (low-volume, library-focused) is at aac-discuss@autoarchitect.ai.
MIT. Forks are allowed, including commercial forks. We trust that the integration moat for downstream platforms (workspace, kanban, deploy pipeline, sandbox) is durable; we don't need protectionism on the substrate.