hmbown/codewhale

1. This is a Rust monorepo centered on an agent harness, not a single app. The primary runtime is split between a terminal UI (crates/tui) and a CLI/headless entrypoint (crates/cli), with shared logic factored into many Rust crates under crates/*.

2. The main execution path starts in the TUI/CLI entrypoints, then flows into the core agent engine in crates/tui/src/core. That engine owns turn management, dispatch, streaming, approvals, tool execution, and loop control. It is the orchestration layer that coordinates everything else.

3. User interaction is UI-driven in crates/tui/src/tui: command palette, session picker, model/provider picker, transcript rendering, status/footer, onboarding, and input handling. The TUI does not implement agent logic itself; it renders state from the core engine and sends user intents back into the turn loop.

4. The agent loop builds each turn from session state, project context, memory, skills, prompts, and model/provider configuration. Relevant subsystems here are project_context, memory, skills, prompts, model_catalog, model_routing, provider_adapter, and session_manager. This is where the harness decides what the model sees and which route/model is used.

5. Provider access is abstracted behind client/adapters in crates/tui/src/client, llm_client, oauth, tls, and model/provider registry modules. The README makes clear that the system supports many providers plus local runtimes like Ollama, vLLM, and SGLang, and that Anthropic/OpenAI are handled through native adapters rather than a generic shim.

6. Tool use is a first-class subsystem. The tool registry and implementations live under crates/tui/src/tools, covering file access, shell, git, web/search, MCP, subagents, patch/apply, review, tasking, and specialized utilities. Tool calls are parsed by the core engine, routed to the right executor, and their outputs are fed back into the same turn.

7. Safety is enforced as runtime policy, not prompt text. Tool execution goes through approval gates, exec-policy checks, and OS sandbox backends under crates/tui/src/sandbox and crates/execpolicy. The repository explicitly supports multiple sandbox mechanisms such as bwrap, Landlock, Seatbelt, seccomp, and Windows-specific handling.

8. Persistence and rollback are built into session handling. The system includes session/state crates, side-snapshot logic, composer/history/stash support, and /restore behavior that can roll back prior turns without touching the user’s main git history. The architecture therefore keeps “session memory” separate from the project repository.

9. There is a separate agent-runtime surface for embedding and remote use. crates/app-server exposes an HTTP/chat-completions style server, while the TUI also contains runtime and ACP/MCP-related modules. The README and docs indicate this is intended for GUI/editor integrations, mobile, and service-style usage, not just terminal interaction.

10. Multi-agent and multi-worker orchestration is another boundary. crates/tui/src/fleet handles scheduling, workers, ledgers, task specs, and host/runtime coordination, while subagent tooling supports concurrent helper agents inside a session. This is the layer for parallel investigation/implementation rather than single-threaded turns.

11. Configuration, secrets, and trust are handled as dedicated subsystems rather than ad hoc env reads. crates/config, crates/secrets, crates/state, and crates/hooks manage provider keys, persisted settings, repo-local constitution/hooks, and durable state. The README also notes compatibility with older config paths and repo-level policy files.

12. The repo includes several integration surfaces outside the Rust harness. integrations/* contains Node-based bridges for Feishu, Telegram, and Weixin; extensions/vscode provides a VS Code extension; web/ is a Next.js/Tailwind site with admin/feed/API routes; and npm/* packages wrap the Rust binaries for distribution. These are front-ends and connectors, not the core agent engine.

13. Release, deployment, and distribution are first-class parts of the architecture. There are Docker, Nix, Homebrew, Cargo, npm, GitHub Actions, Tencent Lighthouse deployment assets, and release scripts. That means the repo ships the same core harness through multiple packaging and hosting channels, but the central runtime remains the Rust workspace.

14. For an architecture diagram, the clearest high-level flow is: user/UI or remote API → session/core engine → prompt/context assembly → provider client → streamed model response → tool/approval/sandbox execution → updated session state and transcript → optional rollback/persistence. Everything else in the repo supports one of those stages or provides an alternate entry surface into them.