yashusingh005/openclaude

1. Product shape

OpenClaude is a terminal-first coding agent runtime, not just a chat app. The core experience is a CLI that manages prompts, tool use, agents, sessions, permissions, and streaming model output across multiple provider backends.

2. Top-level entrypoints

The main runtime lives under src/ and is launched through CLI entrypoints in src/entrypoints, src/main.tsx, and bin/. The repo also includes a headless gRPC server, a VS Code extension, a docs site, and a small Python helper layer for alternate provider behaviors.

3. User interaction layer

The terminal UI is built around React + Ink in src/ink, src/components, src/screens, and src/commands. This layer renders the conversation, status lines, dialogs, permissions, tool progress, onboarding, and slash-command flows. It is the presentation boundary between the user and the agent runtime.

4. Conversation and query engine

The central runtime loop is in src/QueryEngine.ts and the src/query / src/utils/query* modules. This layer turns user input into model requests, streams assistant tokens back, interprets tool calls, runs follow-up turns, enforces stop/compact/goal transitions, and maintains the conversation lifecycle.

5. Provider and model abstraction

src/integrations, src/services/api, and src/utils/provider* form the provider routing layer. It normalizes many backends into one model interface: OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth/Codex, Ollama, Atomic Chat, Fireworks, Bedrock, Vertex, and vendor-specific gateways. Settings and auto-detection determine which endpoint, model, auth method, and usage/reporting behavior apply.

6. Tool execution boundary

Tools are a major subsystem under src/tools and src/services/tools. The agent can invoke bash, file read/write/edit, grep/glob, web fetch/search, MCP tools, tasks, agents, notebook/edit operations, and specialized control tools. The runtime separates tool schema/prompting from execution, then feeds results back into the query loop.

7. Permission and sandboxing model

Sensitive actions are gated through src/hooks/toolPermission, src/components/permissions, and src/utils/permissions. This is where bash/file/network/skill/computer-use approvals, sandbox prompts, and danger-mode controls are enforced. The architecture assumes tool calls are untrusted until explicitly approved or policy-allowed.

8. Session, history, and persistence

Conversation state, transcripts, replay data, session identity, resume/fork behavior, and local storage live in src/history.ts, src/state, src/utils/session*, src/services/sessionTranscript, and src/utils/storage. This makes sessions recoverable and enables commands like resume, continue, export, replay, and background logs.

9. Background, remote, and headless execution

There are separate execution paths for background jobs and remote/headless control. src/cli/bg*, src/server, src/remote, src/grpc, and src/bridge handle detached sessions, remote control, direct-connect sessions, gRPC streaming, and bridge-style integrations. These paths expose the same agent engine through different transport and lifecycle boundaries.

10. Agent, tasks, and multi-agent orchestration

src/tools/AgentTool, src/tasks, src/coordinator, and swarm-related utilities implement subagents, teammate/worktree flows, background tasks, and coordinator/worker behavior. The architecture supports nested agent execution with model routing, permission propagation, and task-status reporting back to the main session.

11. Extensibility layers

Plugins, skills, hooks, MCP, LSP, and custom commands are all first-class extension surfaces. The relevant subsystems are in src/plugins, src/skills, src/hooks, src/services/mcp, src/services/lsp, src/commands, and src/utils/hooks. They extend the agent without changing the core query loop, but they do participate in startup checks, discovery, trust, and policy validation.

12. Configuration, auth, and secrets

Runtime behavior is driven by user settings, environment variables, secure storage, and provider profiles. src/utils/settings, src/utils/secureStorage, src/services/oauth, src/utils/auth*, and onboarding commands manage credentials and configuration. The repo explicitly separates secure secret storage from plaintext settings and supports both interactive setup and env-driven configuration.

13. External integrations and helpers

The code also integrates with GitHub, search/fetch services, shell environments, IDEs, and local system capabilities such as tmux, SSH, terminal features, and optional Firecrawl/DuckDuckGo web access. The Python package provides alternate local provider helpers, while the VS Code extension packages the same ecosystem into editor workflows and launch integration.

14. Build, docs, and delivery

The project is built with Bun/Node tooling, tested heavily with Bun tests, and packaged via release workflows. The web/ Astro site is a separate docs/marketing surface, while docs/ contains the operational guides. Architecturally, these are supporting surfaces around the same core CLI/runtime rather than separate product backends.