Agent DevKit

Agent DevKit is a local-first agent engine and official CLI for building, running and extending autonomous AI agents.

The public npm package is agent-devkit; the canonical command is agent. The current version is defined in package.json — it is the single source of truth; this document does not promise a specific release.

Product Direction

Agent DevKit is being shaped as an engine-first project with a production CLI on top:

• Engine/Core: agent runtime, planning loop, capability execution, memory, permissions, background jobs, providers, logs, runs and automations.
• Official CLI: the agent command is the reference product built on the engine for direct terminal usage, local setup, diagnostics and scripting.
• Adapters: MCP is available today. TUI and HTTP/API adapters are future product layers that must consume the same runtime contracts instead of becoming separate cores.

Personas, names, themes and sprites are user-facing customization for the official CLI. They are not the core abstraction of the engine. The core abstractions are AgentManifest, harness, runtime, policies, constraints, capabilities, tools, memory, permissions, providers and execution events.

Status

Active development. The runtime ships an agent loop, CLI and MCP adapters, multi-provider brains with fallback, persisted runs/goals/memory, multi-agent delegation, catalog-driven tooling management, environment inventory and project scaffolding. It also includes a local background runtime for queued jobs, schedules, memory processing, reusable automations and maintenance. Workspace activity runtime support connects projects, sessions, schedules, activities, background jobs and agent runs into one inspectable execution graph.

Agent definitions are canonical JSON manifests in src/assets/agents/*.json and user/local overrides in ~/.agent-devkit/data/agents/*.json. The default harness wrapper lives in src/assets/runtime/harness/default.json; prompt packs are not the core behavior source.

Runtime V2 is composed from AgentManifest, HarnessWrapper, ContextBuilder, policies, constraints, memory, tool runtime and persisted run events. The context builder assembles session, project, memory, recent observations, tools and permissions under the budget declared by the active manifest, then records the sources used in the run trace. Manifest-backed operational tasks validate completion before returning a final answer.

The stable public SDK surface is still being formalized. Current releases are safe to use as the official CLI and internal engine foundation; external SDK authors should treat low-level TypeScript imports as evolving until the public engine contract is explicitly documented.

Release 0.9.4 closes the experimental 0.9.x foundation cycle. The next architecture cycle is expected to focus on a cleaner engine-first 0.10.x line, using the current implementation as product reference rather than as a compatibility constraint for internal structures.

Install

npm install -g agent-devkit

Development

Requires Node.js >=22.12.0.

npm install
npm run check
npm run dev -- --help

Useful scripts:

npm run build
npm run typecheck
npm run lint
npm run test
npm run test:architecture
npm run test:infra
npm run test:app
npm run test:modules
npm run test:modules -- project
npm run test:module -- self
npm run test:modules:changed
npm run check:fast
npm run package:verify
npm run package:pack

Docker Development

Use Docker when you want to validate the project without installing dependencies or the agent command in the host environment.

npm run docker:build
npm run docker:check
npm run docker:agent -- --help
npm run --silent docker:agent -- doctor --json
npm run --silent docker:agent -- init --dry-run
npm run --silent docker:agent -- install node --verify --json
npm run --silent docker:agent -- scaffold list --json
npm run --silent docker:agent -- scaffold plan react-vite --name demo --dir /tmp --json
npm run --silent docker:agent -- background status --json
npm run --silent docker:agent -- background run-once --json
npm run --silent docker:agent -- watch --once --json
npm run --silent docker:agent -- automations list --json
npm run --silent docker:agent -- automations fit "create markdown document" --automation document-template --json
npm run --silent docker:agent -- agents list --json
npm run --silent docker:agent -- agents validate coordinator --json
npm run --silent docker:agent -- reset --dry-run
npm run --silent docker:agent -- update --latest --dry-run
npm run --silent docker:agent -- tools --json

Interactive CLI agent runs are also executed through the container:

npm run docker:agent
npm run docker:agent -- "analyze this repository"

For debugging inside the same development image:

npm run docker:shell

Architecture

The project is organized around explicit boundaries:

src/
  app/
    cli/
    mcp/
    tui/        # future adapter/design surface; not the core runtime

  modules/
    <module>/
      <module>.index.ts
      <module>.config.ts
      <module>.bind.ts
      <module>.surface.ts
      surface/
        knowledge.json
        loop.json
        prompt.json
        skill.json
      capabilities/
        <capability>/
          <capability>.entities.ts
          <capability>.repository.ts
          <capability>.service.ts
          <capability>.viewmodel.ts
          <capability>.readme.md
          <capability>.test.ts

  infra/
    assets/
    bases/
    clients/
    files/
    helpers/

  assets/
    mcp/
    scaffolds/
    automations/
    tooling/
    fonts/
    i18n/
    images/
    themes/

Rules:

• app owns entrypoints and presentation adapters: CLI, MCP and future TUI/API.
• app must execute capabilities through the shared tool runtime when exposing generic tools.
• CLI is the official reference product built on the engine; it must not become the engine itself.
• modules owns product capabilities as isolated vertical slices.
• A module groups capabilities from the same functional domain; it is not an agent.
• A module surface is the canonical agentic interface for that domain.
• Surface capability metadata is derived from capability configs to avoid drift.
• The tool runtime is the canonical execution socket for CLI, MCP, future TUI/API and agent loops.
• The background runtime is the canonical async execution socket. Features dispatch jobs through BackgroundDispatcherPort; retry, locks, pid/process control, permissions, worker pool status and audit belong to src/infra/background.
• A capability owns its entities, service, repository implementation, view model and tests.
• infra contains only global low-level bases and reusable helpers.
• Capability services must return Result<left, right> from infra/bases/result.ts.
• Module configs must bind their test suites through infra/bases/module.ts.
• Module binders must return Result through infra/bases/bind.ts.
• Capabilities and repositories must implement the contracts from infra/bases/capability.ts.
• Module surface files must pass the minimum schemas defined by infra/bases/surface.ts.
• Concrete clients live in infra/clients; database contracts stay in infra/bases/database.ts.
• Postgres and Redis clients must use injected executors.
• File serialization lives in infra/files and supports JSON, TXT, MD and PDF/binary payloads.
• Asset loading lives in infra/assets and reads from the canonical src/assets folders.
• Canonical external integration catalogs live in src/assets/tooling, src/assets/mcp and src/assets/scaffolds; canonical reusable automations live in src/assets/automations; local learned definitions live under ~/.agent-devkit/data/.
• Canonical agent definitions live in src/assets/agents/*.json; local agent manifests live in ~/.agent-devkit/data/agents/*.json.
• The runtime harness lives in src/assets/runtime/harness/default.json.
• The formal context builder lives in src/agent/agent.context_builder.ts and must enforce manifest context budgets instead of loading unbounded history.
• Runtime finalization must run harness validation for manifest-backed operational tasks before returning a final answer.
• app calls module bindings instead of reaching into filesystem, npm or process details directly.
• User-facing persona/character settings belong to CLI/user personalization layers and must not leak into engine contracts such as capability schemas, tool runtime envelopes or worker manifests.

Distribution

The package is npm-first and publishes the agent binary from dist/main.js. Standalone binaries are out of scope for now.

Installing the npm package must not create runtime folders or project files. State is created only when the user runs the tool:

npm install -g agent-devkit
  installs the agent command only

agent
  may create ~/.agent-devkit when global state is needed

agent init
  may create <project>/.agent-devkit for project-local state

When .agent-devkit/ exists, it should concentrate Agent DevKit state for that scope instead of spreading generated files across unrelated project paths. Runtime data uses a canonical local store layout:

~/.agent-devkit/
  data/
    preferences/
    personalization/
    logs/
    secrets/
    context/
    automations/
      audit.jsonl
      candidates/
  keys/

data/ contains generated runtime data. keys/ contains local key material and is intentionally kept outside data/.

Maintenance commands:

agent reset --dry-run
agent reset --yes
agent reset -g --dry-run
agent update --latest --dry-run
agent update <version> --dry-run
agent update <version> --yes
agent preferences
agent preferences --json
agent preferences themes
agent preferences set-theme forest-teal
agent preferences update --theme ocean-blue
agent projects
agent projects create --name "Agent DevKit" --path .
agent projects open .
agent projects sessions <project-id>
agent projects activities <project-id>
agent projects schedules <project-id>
agent projects runs <project-id>
agent sessions
agent sessions list --project <project-id>
agent sessions create --title "Planning"
agent sessions activities <session-id>
agent sessions runs <session-id>
agent sessions search "memory"
agent sessions resume <session-id>
agent activities list --project <project-id>
agent activities show <activity-id>
agent activities watch --project <project-id>
agent runs
agent runs --project <project-id>
agent runs --session <session-id>
agent runs --activity <activity-id>
agent runs show <run-id>
agent runs events <run-id>
agent runs resume <run-id>
agent schedule create --title "Daily review" --task "Review project status" --project <project-id> --every 1h
agent schedule run <schedule-id>
agent schedule history <schedule-id>
agent watch
agent watch --once --json
agent watch --background --memory --logs
agent watch activities
agent watch sessions
agent watch project <project-id>
agent automations list
agent automations search "task"
agent automations fit "task" --automation document-template
agent automations run document-template --input '{"outputPath":"./doc.md"}' --yes
agent automations candidate create ./my-automation --yes
agent automations curator status
agent agents
agent agents list
agent agents show coordinator
agent agents validate coordinator
agent agents resolve kit
agent goals
agent goals create "Ship the release"
agent memory
agent memory learn "User prefers concise replies" --kind preference
agent integrations
agent integrations mcp catalog
agent integrations mcp register-catalog playwright --yes
agent tools
agent tools --json
agent env scan --scope full --persist --json
agent env inventory
agent env background status
agent install node --dry-run
agent install node --verify
agent tooling list
agent tooling plan-install gemini
agent tooling upgrade claude --yes
agent scaffold list
agent scaffold show flutter-app
agent scaffold plan react-vite --name food-delivery --dir .
agent scaffold create node-cli --name demo-cli --dir /tmp --yes
agent run project.doctor --input '{}' --json
agent run environment.tooling --input '{"action":"detect","toolingId":"node"}' --json
agent run project.scaffold --input '{"action":"plan","id":"react-vite","variables":{"name":"demo","directory":"."}}' --json
agent run project.reset --input '{"confirmed":true,"dryRun":false,"homeDirectory":"/tmp/home","projectRoot":"/tmp/project","scope":"project"}' --approve --json
agent mcp
agent mcp stdio
agent mcp http --port 3333 --origin http://localhost:3333

Initial themes:

• default-purple
• forest-teal
• ocean-blue
• ember-amber
• rose-pink
• slate-neutral
• high-contrast

reset removes only Agent DevKit state folders and executes destructive work only with --yes. update plans an npm global install by default and executes it only with --yes.

Tool Runtime

The generic tool runtime lets any interface discover and invoke capabilities without importing command-specific code.

agent tools --json
agent run <capabilityId> --input '<json>' --json

agent tools --json returns each capability id, module, risk, approval rule, input JSON Schema and output JSON Schema. agent run validates the JSON input, checks approval requirements, executes the capability and returns a structured runtime envelope:

{
  "status": "succeeded",
  "capabilityId": "project.doctor",
  "risk": "read-only",
  "input": {},
  "output": {}
}

Risky capabilities return approval_required unless --approve is passed. MCP uses the same runtime contract, so future TUI/API adapters and agent-loop execution should also plug into this layer instead of calling capabilities directly.

Pack trust model

Packs execute with the full privileges of the agent process: node runners are imported in-process and command runners spawn as child processes (no shell). Install only packs you trust — the approval gate (required by default) is the execution safety net, not a sandbox. command runners receive a minimal environment (PATH, HOME, LANG) and the JSON input via stdin, so parent secrets and provider keys are never inherited.

Agent Runtime, Memory and Integrations

The agentic runtime persists every run under ~/.agent-devkit/data/runtime/ (run.json, events.jsonl, plan.json) with goals in data/runtime/goals/. Runs are inspectable and resumable through agent runs and agent goals. Direct capability calls from CLI, MCP and future TUI/API adapters act with the user's own privileges; the approval gates protect the agentic path.

Workspace work is modeled as:

Project -> Session -> Activity -> Run/Job

• Project is the durable workspace identity, usually detected/opened from a filesystem root.
• Session is the conversation/work context inside a project, with scope roots for subfolders touched during the work.
• Activity is the user-visible operational unit that correlates schedules, background jobs and runtime runs.
• Run stores agent events/plans/results; Job stores queue, retry, lock and worker state.

This lets users and agents list work by project, session, activity, schedule, run or job without creating another scheduler or storage layer.

agent watch provides a live terminal snapshot of the runtime: background queue and workers, projects, sessions, activities, schedules, jobs, recent runs, memory manager, automations and recent log errors/warnings. The same data is available as the read-only runtime.watch capability, so CLI, MCP and the agent consume one shared observability contract.

Global memory lives in the memory module: records have kind (fact, preference, pattern, decision, episode), status (candidate, active, rejected, forgotten), confidence, evidence refs and an audit trail. Inferred learning enters as candidate; explicit user input can enter as active. Chat and the task loop retrieve relevant memory before responding.

External MCP servers are registered through agent integrations and their tools are exposed to the agent through the composite tool runtime as mcp.<server>.<tool>, classified by risk and requiring explicit approval by default.

MCP Server

Agent DevKit exposes its runtime tools through a real MCP server.

For local MCP hosts that launch a subprocess, use stdio:

agent mcp
agent mcp stdio

Add Agent DevKit to a stdio MCP host such as Claude Desktop by pointing its claude_desktop_config.json at the installed agent binary:

{
  "mcpServers": {
    "agent-devkit": {
      "command": "agent",
      "args": ["mcp", "stdio"]
    }
  }
}

For local HTTP clients, use Streamable HTTP on the single /mcp endpoint:

agent mcp http --host 127.0.0.1 --port 3333

HTTP binds to 127.0.0.1 by default. If the client sends an Origin header, that origin must be explicitly allowed:

agent mcp http --port 3333 --origin http://localhost:3333

MCP tools are derived from ToolRuntime.listTools(). Calls execute through ToolRuntime.execute() and return the same structured runtime envelope in a text JSON MCP result.

Risky tools require explicit approval. MCP callers can pass control metadata that is removed before capability validation:

{
  "_agent": {
    "approved": true
  },
  "confirmed": true,
  "dryRun": true,
  "homeDirectory": "/tmp/home",
  "projectRoot": "/tmp/project",
  "scope": "project"
}

CLI and MCP logging must not persist raw tool inputs. Sensitive CLI flags such as agent run --input are redacted before usage and technical logs are written.

Environment Tooling

Agent DevKit has a catalog-driven tooling lifecycle module exposed as the environment.tooling capability. CLI, MCP and the agent runtime use this same capability to detect, doctor, inspect versions, plan, install, upgrade, downgrade and uninstall supported tools.

agent install node --dry-run
agent install node --verify --json
agent install --node --verify
agent tooling list
agent tooling detect ollama
agent tooling plan-install gemini
agent tooling install gemini --yes
agent run environment.tooling --input '{"action":"detect","toolingId":"node"}' --json

Official tooling definitions live in src/assets/tooling/. User-learned or promoted definitions live under ~/.agent-devkit/data/tooling/ and are loaded through the same catalog.

Environment Inventory and MCP Catalog

The environment module can scan the local machine, persist an inventory and let the agent answer later without rescanning every time.

agent env scan --scope quick --json
agent env scan --scope full --persist --root ~/dev --json
agent env inventory
agent env inventory projects
agent env inventory mcp
agent env background enable --root ~/dev --cadence weekly --yes
agent env background run-now --yes

Full scans can discover PATH commands, supported tooling, project markers and external MCP config files. Persisted inventory is stored under ~/.agent-devkit/data/environment/. agent env background run-now queues an environment.scan job in the background runtime; use agent background run-once or a running background process to execute it.

Canonical MCP server definitions live in src/assets/mcp/. User-added or imported MCP definitions live under ~/.agent-devkit/data/mcp/ and are managed through agent integrations mcp.

Project Scaffolding

Project scaffolds are catalog definitions consumed by CLI, MCP and the agent runtime through the project.scaffold capability.

agent scaffold list
agent scaffold show next-app
agent scaffold plan flutter-app --name delivery_app --dir ~/dev
agent scaffold create node-cli --name demo-cli --dir /tmp --yes
agent scaffold validate react-vite --name demo --dir /tmp

Built-in definitions live in src/assets/scaffolds/. Local draft and promoted definitions live under ~/.agent-devkit/data/scaffolds/.

Internal Docs

The local docs/ folder is intentionally ignored by Git. Public documentation belongs in root files such as this README, AGENT.md, and .github/.