# OpenClaude

> One terminal coding agent across cloud APIs, gateways and local model backends

- Category: AI Coding / Autonomous Coding Agents
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/Twigpine/openclaude
- Canonical page: https://ai-tldr.dev/tools/openclaude/

## In short

OpenClaude is an open-source coding-agent CLI that talks to cloud and local model providers from a single terminal-first workflow — prompts, tools, agents, MCP, slash commands and streaming output stay the same whichever backend is behind them. It sits in the Autonomous Coding Agents category of the AI Coding tools and is open-source, written in TypeScript and licensed MIT.

## Overview

OpenClaude is an open-source coding-agent CLI that talks to cloud and local model providers from a single terminal-first workflow — prompts, tools, agents, MCP, slash commands and streaming output stay the same whichever backend is behind them. Rather than picking a provider for you, it ships guided setup: run `/provider` inside the CLI and it walks you through configuration and saves a reusable profile.

The provider table is unusually wide. Any OpenAI-compatible `/v1` server works, which covers OpenAI, OpenRouter, DeepSeek, Groq, Mistral and LM Studio among others, and on top of that sit first-class routes for Gemini, GitHub Models (via an `/onboard-github` flow), Codex and Codex OAuth, Fireworks AI, Cloudflare Workers AI, Bedrock, Vertex and Foundry for the Anthropic family, a set of aggregator gateways, and local inference through Ollama or Atomic Chat with no API key at all.

The agent itself does the usual tool-driven work — bash, file read/write/edit, grep, glob, sub-agents, tasks, MCP and slash commands — with multi-step tool loops and streaming token output. Around that are conveniences worth knowing: conversations can be resumed by session id or forked into a new one, long prompts can run detached as background sessions you list, tail and kill, a PageRank-ranked repo map can be injected into context, `WebSearch` falls back to DuckDuckGo for non-Anthropic models (with Firecrawl as the supported alternative), and the whole thing can run headless as a gRPC service for CI pipelines or custom UIs. OpenClaude keeps its own config under `~/.openclaude` and deliberately does not read `~/.claude`, project `.claude/` directories or `CLAUDE_CONFIG_DIR`, so it does not require Claude Code to be installed.

## What it does

- One CLI across OpenAI-compatible APIs, Gemini, GitHub Models, Codex/Codex OAuth, Fireworks, Cloudflare Workers AI, Bedrock/Vertex/Foundry, Ollama and more
- Guided provider setup and saved profiles through `/provider`, stored in `.openclaude-profile.json`
- Tool-driven coding workflows: bash, file read/write/edit, grep, glob, sub-agents, tasks, MCP and slash commands, with streaming output and multi-step tool loops
- Resume a conversation by session id or continue the most recent one in the directory, with `--fork-session` to branch history instead of reusing the transcript
- Background sessions as local child processes — `--bg` to start, `ps`, `logs -f` and `kill` to manage, with terminal outcomes recorded under the config directory
- Per-agent provider and model routing via `agentModels` / `agentRouting`, plus `maxSteps` caps on sub-agent tool steps
- A repo map ranked by PageRank importance that can be auto-injected into context and inspected with `/repomap`
- Headless gRPC server with bidirectional streaming for embedding the agent in other applications or CI/CD pipelines

## Getting started

OpenClaude needs Node.js 22 or newer for npm installs and at runtime; Bun is only needed for source builds and local development. It does not automatically load project .env files — use `/provider`, or pass `--provider-env-file` explicitly.

1. Install

   Arch Linux users can install from the community-maintained AUR package instead. If the install reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal first.

```bash
npm install -g @gitlawb/openclaude@latest

# Arch Linux
paru -S openclaude
```

2. Start it and pick a provider

   Launch the CLI, then run the guided setup. `/onboard-github` is the interactive path for GitHub Models.

```bash
openclaude

# inside OpenClaude:
/provider          # guided provider setup and saved profiles
/onboard-github    # GitHub Models onboarding
```

3. Resume or fork a conversation

   Forking branches the conversation history into a new session id. It is conversation branching only — it does not copy your working tree or create a git worktree.

```bash
openclaude --resume <session-id>
openclaude --continue
openclaude --resume <session-id> --fork-session
```

4. Run something in the background

   Background sessions are local child processes, not a daemon or network service; metadata and logs live under ~/.openclaude/bg-sessions/ unless OPENCLAUDE_CONFIG_DIR points elsewhere.

```bash
openclaude --bg "fix failing tests"
openclaude --bg --name auth-refactor "refactor auth middleware"
openclaude ps
openclaude logs auth-refactor -f
openclaude kill auth-refactor
```

5. Add a better web-fetch path (optional)

   DuckDuckGo is the default free search path for non-Anthropic models but scrapes results and may be rate-limited or blocked. A Firecrawl key switches WebFetch to Firecrawl's scrape endpoint, which handles JavaScript-rendered pages.

```bash
export FIRECRAWL_API_KEY=your-key-here
```

6. Or run it headless

   Starts the gRPC service; a test CLI client ships with the repository and clients can be generated from src/proto/openclaude.proto.

```bash
npm run dev:grpc
```

## When to use it

- Keep one coding-agent workflow while switching between a hosted API, an aggregator gateway and a local Ollama model
- Run a long refactor detached from your terminal and check on it with `ps` and `logs -f`
- Route cheap sub-agents to a small model and hard reasoning to a large one from a single settings file
- Embed an agentic coding loop into CI or a custom UI through the headless gRPC server