A daemon-backed, terminal-native coding agent — autonomous background agents, an in-terminal editor workbench, MCP-native tools, and OS-sandboxed execution.

AgenC Core is the implementation repository for the agenc CLI — an agent that reads your code, runs commands, and edits files from the terminal. It is daemon-backed: a local daemon owns agent/session lifecycle, command execution, permissions, and provider calls, while the interactive TUI, the one-shot --print CLI, and background agents are all clients of it. The live implementation is concentrated in runtime/, with a thin public launcher in packages/agenc/ and daemon service templates in packaging/.

For the subsystem map and how the pieces fit together, see docs/ARCHITECTURE.md.

• Features
• Project status
• Requirements
• Quick start
• Usage
• Configuration
• Architecture
• Development
• Security
• Contributing
• License

• Two front-ends, one engine — an interactive Ink/React TUI and a headless one-shot mode (agenc --print "…"), both driven by the same daemon-owned session engine.
• Background & autonomous agents — fire-and-forget agents that run independently of the foreground UI, each in its own git worktree, attachable and resumable.
• Built-in tools — Bash, file read/write/edit, transactional apply_patch, web fetch/search, LSP, MCP, and recursive sub-agents — with read-before-write and atomic-patch safety.
• MCP-native — an outbound MCP client (tool/resource/prompt bridges) and an MCP server framework, including enterprise XAA (SEP-990) auth.
• Layered safety — a mode-based permission system plus an opt-in OS sandbox (bubblewrap/Landlock on Linux, Seatbelt on macOS) for shell execution.
• In-terminal workbench — project explorer, code preview, and an editable BUFFER surface that prefers an embedded nvim --embed.
• Provider-neutral — defaults to xAI (grok-4.3); also speaks the Anthropic SDK, the OpenAI-compatible HTTP protocol, and local Ollama.
• Durable sessions — append-only rollout logs + SQLite state written atomically, with --continue / --resume.

Pre-release (0.2.0, private). The codebase is type-clean (0 @ts-nocheck, tsc at 0 errors) with ~12,000 passing tests, and the daemon / persistence / permission cores are mature (WAL SQLite, atomic rollout writes, an AST-backed Bash permission layer, transactional file edits). It is not yet published to a registry — build from source (below). A top-level LICENSE is being finalized ahead of the first public release.

• Node.js >= 25 (declared in runtime/package.json engines).
• npm 11.x (declared via packageManager).
• ripgrep (rg) on PATH for file search. No binary is bundled, so install it from your package manager (brew install ripgrep, apt install ripgrep, winget install BurntSushi.ripgrep.MSVC) and confirm rg --version. Without it Glob fails and Grep drops to a slower pure-JS fallback; agenc doctor reports the status with a fix hint.
• A provider before real model calls. The default is xAI (XAI_API_KEY, also accepts GROK_API_KEY); the default model is grok-4.3 (AGENC_MODEL overrides). Inspect setup with agenc providers, agenc login, and agenc config.

Build from source and run the CLI:

npm install
npm run build
node runtime/bin/agenc --help

Start the interactive TUI:

npm run start

Run a one-shot prompt without the TUI:

node runtime/bin/agenc --no-tui "summarize this repository"

Initialize local project config:

node runtime/bin/agenc init
node runtime/bin/agenc config validate

agenc [options] [PROMPT]
agenc -p|--print [options] [PROMPT]
agenc help [command]
agenc init [--force]
agenc <login|logout|whoami>
agenc providers [--json] [--no-local-check]
agenc config <show|get|set|unset|validate|edit|path>
agenc plugin <command> [options]
agenc permissions <command>
agenc state <export <agent-id>|import>
agenc daemon <start [--foreground]|stop|status|reload|restart>
agenc agent <start <objective>|list|attach <id>|stop <id>|logs <id>>
agenc mcp <serve|add|list|get|remove|add-json|add-from-agenc-desktop|reset-project-choices|doctor|xaa>
agenc doctor [--json]

agenc doctor diagnoses the installation and environment (version, install type, ripgrep status, auto-update permissions, PATH/glob warnings + fixes); --json emits the raw diagnostic. agenc mcp doctor does the MCP-specific checks, and agenc mcp xaa (setup|login|show|clear) drives the Cross-App Access / Enterprise Managed Authorization flow (SEP-990) for enterprise-managed MCP servers.

Common flags:

-p, --print                                   headless one-shot mode
--no-tui                                       run without the TUI
--continue                                     continue the latest session
--resume <session-id>                          resume a specific session
--profile <name>                               use a named config profile
--provider <name>                              override the provider
--model <id|provider:id>                       override the model
--permission-mode <mode>                       set the approval mode
--autonomous, --proactive                      enable autonomous ticks
--dangerously-bypass-approvals-and-sandbox     bypass approvals + sandbox
--yolo                                          alias for the bypass flag
--allow-dangerously-skip-permissions           skip approval prompts
--image <file|url|data-url>                    attach an image

Use agenc help <command> for command-specific help.

The daemon is the local control plane — it owns agent/session lifecycle, JSON-RPC dispatch, command execution, provider-key vending, permission requests, realtime methods, health checks, and background-agent attachment.

node runtime/bin/agenc daemon status
node runtime/bin/agenc daemon start [--foreground]
node runtime/bin/agenc daemon reload
node runtime/bin/agenc daemon restart
node runtime/bin/agenc daemon stop

The launcher in packages/agenc/ autostarts the daemon before invoking runtime commands unless AGENC_DAEMON_AUTOSTART=0; the launcher's daemon-ready timeout is AGENC_DAEMON_READY_TIMEOUT_MS.

Daemon-managed sessions that run independently of the foreground TUI:

node runtime/bin/agenc agent start "fix the failing parser test"
node runtime/bin/agenc agent start --unattended-allow read,grep "audit imports"
node runtime/bin/agenc agent list
node runtime/bin/agenc agent attach <agent-id>
node runtime/bin/agenc agent logs <agent-id>
node runtime/bin/agenc agent stop <agent-id>

The TUI includes a workbench — a project explorer, a read-only code preview, and an editable BUFFER surface for editing files without leaving the terminal. BUFFER supports three editor providers:

• Embedded Neovim (preferred) — AgenC launches nvim --embed and owns process lifecycle, rendering, and file safety, while Neovim owns Vim semantics.
• Inline fallback — a basic built-in editor used only when Neovim is unavailable; fallback-only, and it does not claim exact Vim behavior.
• External editor — explicit handoff to $VISUAL/$EDITOR (nvim, vim, vi, nano, …).

Security note: in auto mode the embedded-Neovim path loads your full Neovim config (init.lua) and plugins, which execute as your user. See docs/embedded-neovim-buffer.md for the trust boundary and how to run Neovim isolated under unattended agents.

The embedded-Neovim PTY lifecycle (including the "kill the TUI mid-edit and leave no orphaned nvim child" guarantee) is exercised by the check:tui-workbench-buffer-neovim scenario gate.

Runtime state lives under AGENC_HOME (default ~/.agenc) — the daemon's pid file, cookie, socket, config, per-project state, sessions, and logs all share that home. Key knobs:

Principal runtime subsystems (runtime/src):

bin/            CLI entrypoint + subcommand adapters
app-server/     the daemon: dispatch, transports, auth, lifecycle, health
session/        session store, turns, transcript, rollout, autonomous mode
agents/         background-agent state, registry, worktree, status
llm/            provider-neutral model/client/request handling
services/       concrete provider wire layer, caching, cost
tools/          built-in model tools
permissions/    trust, approval, permission rules, sandbox policy
sandbox/        OS sandbox launch helpers
mcp-client/     outbound MCP client (tool/resource/prompt bridges)
mcp-server/     MCP server framework + transports
config/ state/  config schema/store/migrations, SQLite project state
transaction-guard/  opt-in SLM tool-call guard (see Security)
tui/            the Ink/React terminal UI

The full subsystem map (process model, on-disk state, render stack) is in docs/ARCHITECTURE.md.

From the repo root:

npm run typecheck        # tsc --noEmit (keep at 0 errors)
npm run build            # tsup build → runtime/dist + VERSION
npm run test             # typecheck + full vitest suite
npm run test:bun         # isolated Bun suite (one file per process)
npm run validate:runtime # typecheck + build + PTY startup smoke

Runtime-scoped gates (npm --workspace=@tetsuo-ai/runtime run <name>):

check:tui-runtime-startup   # launch agenc / agenc --yolo in real PTYs
check:tui-e2e               # TUI scenario suite (-- --filter <name>)
check:daemon-errors
check:llm-pipeline
check:e2e-all               # daemon-errors + llm-pipeline + tui-e2e
check:unused                # knip (unused exports/files/deps)

check:tui-runtime-startup imports the built TUI bundle and launches agenc and agenc --yolo in real pseudo-terminals at several viewport sizes — keep it in the validation path for anything touching the TUI, daemon startup, package entrypoints, or built artifacts.

npm run build compiles the runtime with tsup, writes runtime/dist/VERSION, copies runtime policy assets, and verifies the package entrypoints. The generated runtime/dist/ tree is build output, not source.

Shell execution and file mutation flow through a mode-based permission layer; an opt-in OS sandbox confines shell commands at the kernel level (bubblewrap / Landlock on Linux, Seatbelt on macOS). Mutating tools are guarded — file edits enforce read-before-write + mtime-drift checks, and apply_patch applies multi-file patches transactionally (plan → commit → roll back on any failure).

The runtime also ships an opt-in SLM transaction guard (CourtGuard-style) for Solana transaction-like tool calls: it runs at the tool-dispatch boundary before execution, fails closed, defaults to local Ollama (gemma4:e4b), and has an explicit DevNet live-validation path. See docs/security/slm-transaction-guard.md.

Daemon service supervisor templates live under packaging/ (systemd/agenc-daemon.service, launchd/dev.agenc.daemon.plist, windows/agenc-daemon.xml); each runs agenc daemon start --foreground.

1. Branch off main (never commit directly to it).
2. Make the change with a revert-sensitive test where a bug is involved.
3. Verify locally — the gates are authoritative because CI (.github/workflows/ci.yml) is manual-only:
   • npm run typecheck → 0 errors (and no new @ts-nocheck),
   • npm run test → green,
   • npm run check:tui-runtime-startup --workspace=@tetsuo-ai/runtime for TUI/daemon/entrypoint changes.
4. Use conventional commits (fix(runtime): …); open a PR and squash-merge. Don't bypass git hooks (--no-verify).

A pre-commit hook is provided in .githooks/ (build + PTY startup smoke); enable it with git config core.hooksPath .githooks.

Pre-release. The runtime package metadata declares MIT (runtime/package.json); a top-level LICENSE/NOTICE is being finalized ahead of the first public release. Until then the repository is private.