Architecture — Logician

01 — Package map

Four packages, one process

Everything runs locally in a single Node process. No services to orchestrate — packages are TypeScript workspaces, not network boundaries.

02 — Dependency shape

Package dependencies converge on agent-core, with the terminal UI composing the complete runtime:

tui

coding-agent

agent-capabilities

agent-core

agent-core has no internal dependencies — it's the foundation every other package builds on.
agent-capabilities depends only on agent-core, adding todos, user prompts, subagents, and reasoning strategies.
coding-agent is the orchestration layer — it combines agent-core and agent-capabilities with sessions, tools, skills, configuration, and MCP.
tui sits on top of everything: agent-core, agent-capabilities, and coding-agent.

03 — Package detail

@logician/agent-core

Lean agent engine: loop, harness, hooks, types. Zero internal dependencies — the foundation layer.

AgentHarness and runAgentLoop() drive the turn loop: intake → model call → tool execution → hooks → next turn.
hooks/{builtin,extensions,native} — pre/post-tool hook chains, budget tracking, hook metrics.
message-queue/ — steering, follow-ups, and queued input between turns.
compaction/ — context compaction and recovery when a session approaches its token budget.
compatibility/claude-code/ — a Claude Code compatibility layer (hooks, plugin executor/manager).
tools/shared/ — permissions, tool-call parsing, plugin loading, the tool registry.
Backend abstraction over any OpenAI-compatible API (OpenAIBackend), with typed, retryable BackendError.

@logician/agent-capabilities

Behaviors layered on the core loop: task tracking, user prompts, subagents, and reasoning strategies.

todo/ — task tracking with status transitions.
ask-user/ — structured prompts back to the user mid-turn.
subagents/ — child-agent spawning and delegation, isolated worktrees/context.
reasoners/ — nine strategies: SSR, Tree of Thoughts, Graph of Thoughts, Reflexion, Best-of-N, Self-Consistency, Auto-CoT, In-Context CoT, plus a shared base + registry.
eoh/ — an evolutionary optimization engine (population, evaluator). Opt-in: not re-exported from the package's main entry point.

@logician/coding-agent

Orchestration layer: sessions, config, skills, slash commands, and model resolution — where everything else gets wired together.

runtime/bridge.ts (AgentCoreBridge) — the largest file in the repo; connects the harness, capabilities, sessions, and tools into one runtime.
runtime/ also holds LoopManager, GoalManager, an LSP manager for language-server integration, and post-edit diagnostics.
tools/ — file ops, search, system, and web tools (see tool table below).
mcp/ — an MCP client with both StdioMcpClient and HttpMcpClient (streamable HTTP) transports, plus a connection manager.
sessions/ — SessionStore and transcript persistence, including bookmarks and rewind.
context-files/, trust/, commands/slash-commands.ts — repo context loading, permission trust, and the slash-command registry.

@logician/tui

The terminal UI. Streams model output, tool traces, and reasoning live to any VT100-compatible terminal — local, SSH, or tmux.

layers/presentation — rendering pipeline.
layers/input — keybindings, input bar, steering queue.
layers/theme — theme system, theme selector.
layers/events / layers/core — event plumbing, TUI core state machine.
components/ — status bar, transcript display, MCP manager, reasoner selector, EOH panel, popups/overlays.
Entry point handles exec and doctor CLI modes before booting the interactive TUI.

04 — The turn loop

Every turn moves through the same pipeline, whether it's a plain chat message, a tool call, or a subagent delegating back to its parent.

Task scope and intake — initializes the registry, result cache, system prompt, and task status, then drains steering at turn boundaries and follow-ups when the agent would otherwise become idle.
Provider pipeline — context transforms run before transport conversion; request and payload hooks can modify provider options, and thinking, text, and tool-call deltas stream as ordered events.
Recovery and compaction — retryable provider failures use bounded retry; context-full failures compact to a target budget and retry. Proactive compaction also runs while preparing a later turn.
Tool batches — each call is prepared and permission-checked before internal and user hooks run. Parallel-safe calls execute concurrently around sequential barriers, while result messages retain the model's original order.
Loop or finish — context accounting, diagnostics, refreshed configuration, and queued messages can continue the loop. Stop policies, acceptance verification, optional reflection, and structured task status determine the final run outcome.

05 — Outside the process

Everything the agent can touch outside its own process goes through a typed tool call — visible, loggable, and gated by the permission mode.

LLM backend

Any OpenAI-compatible API — local (llama.cpp) or hosted, swappable with a single config change.

MCP servers

stdio and streamable-HTTP transports via coding-agent/mcp.

SearXNG

web_search / web_fetch against a local or remote SearXNG instance.

Filesystem · Git

bash, ripgrep-backed grep, fd/find-backed find, and git status/diff/log.