housetan218/claude-code-haha

1. This is a terminal-first AI agent client, not a web app.

The repository packages a Claude Code–style interactive TUI plus a --print headless mode, all running on Bun/TypeScript with React + Ink for terminal rendering. The main external dependency boundary is an Anthropic-compatible API endpoint, which can be customized for providers like MiniMax or OpenRouter.

2. Launch path starts at the wrapper script and preload.

bin/claude-haha is the user-facing executable, preload.ts prepares runtime globals/environment, and src/entrypoints/cli.tsx is the main CLI entry. From there the app can route into the full TUI, headless print mode, or the recovery CLI fallback in src/localRecoveryCli.ts.

3. Startup and session bootstrap form the first major subsystem.

src/setup.ts, src/bootstrap/*, src/state/*, and src/projectOnboardingState.ts establish app state, settings, workspace context, and session identity before the interface becomes interactive. This is where environment/config, user settings, and persisted session data are loaded and normalized.

4. The terminal UI is a React/Ink application with custom rendering infrastructure.

src/main.tsx, src/screens/*, src/components/*, and the large src/ink/* subtree make up the interactive interface. Ink is not just used as a component library here; the repo includes a substantial custom terminal renderer, event system, layout engine, and text measurement logic, which is a key architectural boundary for diagramming.

5. User input flows through command parsing, keybinding resolution, and prompt processors.

Keystrokes and slash commands are handled through src/keybindings/*, src/commands/*, and src/utils/processUserInput/*. The app distinguishes freeform prompts, slash commands, and shell-style inputs, then routes them into the appropriate execution or UI action.

6. The agent/tool execution pipeline is the core runtime loop.

src/tools/*, src/services/tools/*, src/query/*, src/QueryEngine.ts, src/Task.ts, and src/tasks/* model the work the assistant performs. Tool implementations cover file I/O, bash/powershell, LSP, web fetch/search, MCP, tasks, agents, and remote triggers; services/tools/* orchestrates streaming execution, hooks, and result aggregation.

7. Permissions and sandboxing are a major architectural boundary.

Tool use is mediated by src/hooks/toolPermission/*, src/components/permissions/*, src/utils/permissions/*, and sandbox-related code under src/components/sandbox/* and src/utils/sandbox/*. This boundary decides whether a tool can run, whether user approval is required, and how destructive or risky commands are classified.

8. Conversation state, history, and memory are tracked separately from the UI.

src/history.ts, src/assistant/sessionHistory.ts, src/hooks/useAssistantHistory.ts, src/memdir/*, and src/services/SessionMemory/* handle message history, memory files, summaries, and retrieval. This data layer feeds prompt construction and session resume/rewind features.

9. There is a substantial integration layer for remote/control-plane workflows.

src/bridge/*, src/remote/*, src/server/*, src/upstreamproxy/*, and src/services/oauth/* support remote sessions, bridges, direct connect, and authenticated control channels. These modules separate local interactive execution from remote session management and transport concerns.

10. MCP, LSP, plugins, and skills are the extensibility surface.

src/services/mcp/*, src/services/lsp/*, src/plugins/*, src/skills/*, and the corresponding UI/command surfaces in src/components/mcp/*, src/components/agents/*, and src/commands/* provide pluggable capabilities. Skills and plugins extend behavior, MCP exposes external tool servers, and LSP adds code-aware operations.

11. Supporting services handle model selection, usage, telemetry, and safety.

src/services/api/*, src/services/analytics/*, src/services/compact/*, src/services/voice*, src/services/tokenEstimation.ts, and rate-limit / policy modules manage network calls, cost-aware behavior, telemetry, and operational constraints. The app is designed to adapt model choice, prompt size, and usage reporting without coupling those concerns to the UI.

12. Persistence and configuration are file- and settings-driven.

src/utils/settings/*, src/services/settingsSync/*, src/services/remoteManagedSettings/*, src/utils/sessionStorage*, and src/migrations/* show a strong local-state model with migrations and sync layers. The app persists workspace/session configuration, permissions, plugins, and user preferences across runs.

13. A “session/task” model ties everything together.

Background work is represented as tasks (src/tasks/*), with UI views, status indicators, and resumable execution paths. This makes the app’s main flow: user input → command/tool selection → permission gate → task execution → streamed messages/UI updates → persisted history/state.

14. One important diagram boundary is the recovery/fallback path.

The project explicitly supports a simplified recovery CLI when the full Ink UI cannot start. That means the architecture has two operational modes: the primary interactive TUI and a minimal fallback shell for degraded startup conditions.