mirror of
https://github.com/Gitlawb/openclaude.git
synced 2026-08-24 10:14:19 -05:00
Chore/readme cleanup (#1976)
* docs: README cleanup, green wordmark header, Trendshift badges Header: the startup wordmark (src/constants/brand.ts half-block art) rendered as a green two-shade SVG (docs/assets/openclaude-wordmark.svg, textLength-pinned so rows align in any monospace font), with the three Trendshift badges (daily/monthly/repository) centered beneath it. Cleanup (536 -> ~430 lines, nothing lost): - Agent routing, maxSteps limits, and GitHub Copilot sub-agent tuning moved to docs/agent-routing.md; headless gRPC server moved to docs/grpc-server.md; README keeps linked summaries. - Build/test/validation commands were repeated in three sections — consolidated into one Development section; Contributing links to it. - New "Meet Your Buddy" section documenting the companion heroes and their /buddy commands; added to What Works and Why OpenClaude. - Star History moved from the header flow down beside Community. - Setup Guides indexes the new docs pages; fixed a missing blank line before Repository Structure and a curly quote. All relative links, image paths, and internal anchors validated. Co-Authored-By: OpenClaude <openclaude@gitlawb.com> * docs: pure-rect wordmark for crisp rendering; drop broken Star History The wordmark SVG previously drew the half-block art as monospace <text>, which rendered raggedly (font-dependent glyph stretching and seams). Regenerated as pure SVG rects computed from the brand.ts wordmark grid — no font dependence, pixel-crisp at any size, same two-shade green split. Star History chart removed: the badge endpoint errors and displays a broken image. Co-Authored-By: OpenClaude <openclaude@gitlawb.com> * docs: render the wordmark at full README column width Co-Authored-By: OpenClaude <openclaude@gitlawb.com> --------- Co-authored-by: OpenClaude <openclaude@gitlawb.com>
This commit is contained in:
Kevin Codex
co-authored by
OpenClaude
OpenClaude
parent
d683e85395
commit
14648213a6
@@ -1,4 +1,12 @@
|
||||
# OpenClaude
|
||||
<div align="center">
|
||||
<img src="docs/assets/openclaude-wordmark.svg" alt="OpenClaude — Open terminal for any LLM" width="830">
|
||||
|
||||
<p>
|
||||
<a href="https://trendshift.io/repositories/25807?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-25807" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/25807/daily?language=TypeScript" alt="Gitlawb%2Fopenclaude | Trendshift" width="250" height="55"/></a>
|
||||
<a href="https://trendshift.io/repositories/25807?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-25807" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/25807/monthly?language=TypeScript" alt="Gitlawb%2Fopenclaude | Trendshift" width="250" height="55"/></a>
|
||||
<a href="https://trendshift.io/repositories/25807?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-25807" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/25807" alt="Gitlawb%2Fopenclaude | Trendshift" width="250" height="55"/></a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
OpenClaude is an open-source coding-agent CLI for cloud and local model providers.
|
||||
|
||||
@@ -15,7 +23,7 @@ Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, A
|
||||
OpenClaude is also mirrored to GitLawb:
|
||||
[gitlawb.com/node/repos/z6MkqDnb/openclaude](https://gitlawb.com/node/repos/z6MkqDnb/openclaude)
|
||||
|
||||
[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Sponsors](#sponsors) | [Community](#community)
|
||||
[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Development](#development) | [VS Code Extension](#vs-code-extension) | [Sponsors](#sponsors) | [Community](#community)
|
||||
|
||||
## Sponsors
|
||||
|
||||
@@ -56,17 +64,13 @@ OpenClaude is also mirrored to GitLawb:
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/?repos=gitlawb%2Fopenclaude&type=date&legend=top-left)
|
||||
|
||||
## Why OpenClaude
|
||||
|
||||
- Use one CLI across cloud APIs and local model backends
|
||||
- Save provider profiles inside the app with `/provider`
|
||||
- Run with OpenAI-compatible services, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported providers
|
||||
- Keep coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
|
||||
- Use the bundled VS Code extension for launch integration and theme support
|
||||
- One CLI across cloud APIs and local model backends — no per-provider tooling
|
||||
- Guided provider setup and saved profiles with `/provider`
|
||||
- Coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
|
||||
- A bundled VS Code extension for launch integration and theme support
|
||||
- A pixel-art hero companion who fires an arrow every time you press Enter (really — see [Meet your buddy](#meet-your-buddy))
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -232,6 +236,9 @@ Advanced and source-build guides:
|
||||
|
||||
- [Advanced Setup](docs/advanced-setup.md)
|
||||
- [Smart Auto-Routing](docs/smart-routing.md)
|
||||
- [Agent Routing and Step Limits](docs/agent-routing.md)
|
||||
- [Headless gRPC Server](docs/grpc-server.md)
|
||||
- [Repo Map (codebase intelligence)](docs/repo-map.md)
|
||||
- [Android Install](ANDROID_INSTALL.md)
|
||||
|
||||
## Supported Providers
|
||||
@@ -267,6 +274,30 @@ Advanced and source-build guides:
|
||||
- **Provider profiles**: Guided setup plus saved user-level provider profile support
|
||||
- **Local and remote model backends**: Cloud APIs, local servers, and Apple Silicon local inference
|
||||
- **Codebase intelligence (repo map)**: Structural map of the repository ranked by PageRank importance, auto-injected into context when the `REPO_MAP` flag is enabled or the `REPO_MAP` environment variable is set. Inspect with `/repomap` (2048-token default). See [docs/repo-map.md](docs/repo-map.md) for details.
|
||||
- **A companion with signature moves**: A truecolor pixel-art hero who lives beside your prompt and reacts when you work. See below.
|
||||
|
||||
## Meet Your Buddy
|
||||
|
||||
Run `/buddy` to hatch a companion — a truecolor pixel-art hero who stands
|
||||
beside your prompt, idles, blinks, and fires their signature move every time
|
||||
you submit a message:
|
||||
|
||||
```
|
||||
/buddy hatch (first run) or pet your companion
|
||||
/buddy set robinhood the green archer — arrow shot on every Enter
|
||||
/buddy set kaio gold-haired warrior — charges a full-width energy wave
|
||||
/buddy set strawhat stretchy punch that snaps back
|
||||
/buddy set merlin twinkling sparkle stream
|
||||
/buddy set kage spinning shuriken
|
||||
/buddy set ember dragon fire with a real heat gradient
|
||||
/buddy set corsair cannonball with smoke trail
|
||||
/buddy name Robin rename your companion
|
||||
/buddy set random back to your rolled hero
|
||||
```
|
||||
|
||||
Companions respect `prefersReducedMotion`, degrade gracefully to line art in
|
||||
low-color terminals, and can be silenced with `/buddy mute`. Requires a
|
||||
terminal at least 100 columns wide for the full sprite.
|
||||
|
||||
## Provider Notes
|
||||
|
||||
@@ -280,93 +311,21 @@ OpenClaude supports multiple providers, but behavior is not identical across all
|
||||
- Gitlawb Opengateway is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. It uses one OpenAI-compatible base URL; switch between `mimo-*` and `google/gemini-3.1-flash-lite-preview` with `/model`, and do not pin the base URL to `/v1/xiaomi-mimo`.
|
||||
- Z.AI GLM Coding Plan uses `https://api.z.ai/api/coding/paas/v4` with `glm-5.2` by default. Use `glm-5.2?reasoning=high` for enhanced reasoning, `glm-5.2?reasoning=xhigh` to request Z.AI `reasoning_effort=max`, or `glm-5.2?thinking=disabled` for faster direct answers.
|
||||
- Xiaomi MiMo uses `api-key` header auth on the direct OpenAI-compatible route and currently does not support `/usage` reporting in OpenClaude
|
||||
|
||||
### GitHub Copilot sub-agent optimization
|
||||
|
||||
When CLAUDE_CODE_USE_GITHUB=1, OpenClaude serializes sub-agent execution to reduce GitHub Copilot Premium Request consumption. Default behavior is GITHUB_COPILOT_MAX_SUBAGENTS=1 (synchronous, one sub-agent at a time). Tuning vars (all optional):
|
||||
|
||||
| Var | Effect |
|
||||
|---|---|
|
||||
| GITHUB_COPILOT_MAX_SUBAGENTS=0 | Suppress sub-agents entirely (sub-agents throw an error). |
|
||||
| GITHUB_COPILOT_MAX_SUBAGENTS=1 | Force synchronous execution. **Default.** |
|
||||
| GITHUB_COPILOT_MAX_SUBAGENTS=2..10 | Parsed/clamped but not enforced differently from =1 (any positive cap = synchronous). |
|
||||
| GITHUB_COPILOT_ALLOW_SUBAGENTS=1 | Re-enable parallel/background sub-agents, overriding the cap. |
|
||||
| GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS=1 | Force synchronous execution regardless of cap. |
|
||||
| GITHUB_COPILOT_OPTIMIZATION_DISABLED=1 | Disable all of the above; sub-agents run as before this feature. |
|
||||
|
||||
The `is_async` field reported in the `tengu_agent_tool_selected` event and the agent metadata now reflects the final execution mode (i.e., `false` when synchronous is forced). See `.env.example` for the full descriptions.
|
||||
- GitHub Copilot serializes sub-agent execution by default to reduce Premium Request consumption — see [Agent Routing and Step Limits](docs/agent-routing.md#github-copilot-sub-agent-optimization) for tuning
|
||||
|
||||
For best results, use models with strong tool/function calling support.
|
||||
|
||||
### Agent step limits
|
||||
## Agents
|
||||
|
||||
Custom agents can define `maxSteps` as a positive integer to cap how many tool-use steps a sub-agent may execute. When the limit is reached, OpenClaude stops additional tool calls and asks the sub-agent for a concise final summary covering completed work, findings, remaining tasks, and whether another run is needed. Omitting `maxSteps`, or setting it to an invalid value such as `0` or malformed input, preserves the default unlimited behavior.
|
||||
Route different agents to different models (cost optimization, splitting work
|
||||
by model strength), cap sub-agent tool steps with `maxSteps`, and tune GitHub
|
||||
Copilot sub-agent behavior. All settings-driven:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: bounded-researcher
|
||||
description: Use for focused research with bounded tool use
|
||||
maxSteps: 8
|
||||
---
|
||||
- per-agent provider/model overrides via `agentModels` + `agentRouting` in `~/.openclaude.json`
|
||||
- model-only routes that reuse your current provider's credentials
|
||||
- built-in agents (`Explore`, `Plan`, `verification`) routable by type name
|
||||
|
||||
You are a focused research agent.
|
||||
```
|
||||
|
||||
## Agent Routing
|
||||
|
||||
OpenClaude can route different agents to different models through settings-based routing. This is useful for cost optimization or splitting work by model strength.
|
||||
|
||||
Add to `~/.openclaude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agentModels": {
|
||||
"deepseek-v4-flash": {
|
||||
"base_url": "https://api.deepseek.com/v1",
|
||||
"api_key": "sk-your-key"
|
||||
},
|
||||
"zai-default": {
|
||||
"model": "glm-5.2",
|
||||
"base_url": "https://api.z.ai/api/coding/paas/v4",
|
||||
"api_key": "sk-your-key"
|
||||
},
|
||||
"gpt-4o": {
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-your-key"
|
||||
}
|
||||
},
|
||||
"agentRouting": {
|
||||
"Explore": "deepseek-v4-flash",
|
||||
"Plan": "gpt-4o",
|
||||
"general-purpose": "gpt-4o",
|
||||
"frontend-dev": "zai-default",
|
||||
"default": "gpt-4o"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When no routing match is found, the global provider remains the fallback.
|
||||
|
||||
`agentRouting` values and explicit Agent tool `model` overrides match keys in `agentModels`. By default, that key is also the model string sent to the provider. Set `agentModels.<key>.model` when you want a local route key such as `zai-default` to call a different provider model name such as `glm-5.2`.
|
||||
|
||||
> **Note:** `/provider` changes the global/parent provider for your current session. `agentModels` and `agentRouting` are specifically for configuring per-agent provider overrides while keeping the parent session unchanged.
|
||||
|
||||
> **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep this file private and do not commit it to version control.
|
||||
|
||||
**Model-only routes (same provider):** Omit `base_url` and `api_key` to run an agent on a different model using your *current* provider's endpoint and key — no credential duplication:
|
||||
|
||||
```json
|
||||
{
|
||||
"agentModels": {
|
||||
"mini": { "model": "gpt-5-mini" }
|
||||
},
|
||||
"agentRouting": {
|
||||
"verification": "mini"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Built-in agents are routable by their type name.** Useful keys: `verification` (the read-only auditor that runs before completion), `Explore`, and `Plan`. For example, `"agentRouting": { "verification": "mini" }` runs the verifier on `gpt-5-mini` while your main session stays on its model. Absent any entry, the verifier inherits the main-loop model.
|
||||
See [Agent Routing and Step Limits](docs/agent-routing.md) for the full guide.
|
||||
|
||||
## Web Search and Fetch
|
||||
|
||||
@@ -391,42 +350,15 @@ With Firecrawl enabled:
|
||||
|
||||
Free tier at [firecrawl.dev](https://firecrawl.dev) includes 500 credits. The key is optional.
|
||||
|
||||
---
|
||||
|
||||
## Headless gRPC Server
|
||||
|
||||
OpenClaude can be run as a headless gRPC service, allowing you to integrate its agentic capabilities (tools, bash, file editing) into other applications, CI/CD pipelines, or custom user interfaces. The server uses bidirectional streaming to send real-time text chunks, tool calls, and request permissions for sensitive commands.
|
||||
OpenClaude can run as a headless gRPC service with bidirectional streaming —
|
||||
integrate its agentic capabilities into other applications, CI/CD pipelines,
|
||||
or custom UIs. Start it with `npm run dev:grpc`; a test CLI client ships with
|
||||
the repo. See [Headless gRPC Server](docs/grpc-server.md) for configuration
|
||||
and client generation from `src/proto/openclaude.proto`.
|
||||
|
||||
### 1. Start the gRPC Server
|
||||
|
||||
Start the core engine as a gRPC service on `localhost:50051`:
|
||||
|
||||
```bash
|
||||
npm run dev:grpc
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|-----------|-------------|------------------------------------------------|
|
||||
| `GRPC_PORT` | `50051` | Port the gRPC server listens on |
|
||||
| `GRPC_HOST` | `localhost` | Bind address. Use `0.0.0.0` to expose on all interfaces (not recommended without authentication) |
|
||||
|
||||
### 2. Run the Test CLI Client
|
||||
|
||||
We provide a lightweight CLI client that communicates exclusively over gRPC. It acts just like the main interactive CLI, rendering colors, streaming tokens, and prompting you for tool permissions (y/n) via the gRPC `action_required` event.
|
||||
|
||||
In a separate terminal, run:
|
||||
|
||||
```bash
|
||||
npm run dev:grpc:cli
|
||||
```
|
||||
|
||||
*Note: The gRPC definitions are located in `src/proto/openclaude.proto`. You can use this file to generate clients in Python, Go, Rust, or any other language.*
|
||||
|
||||
---
|
||||
|
||||
## Source Build And Local Development
|
||||
## Development
|
||||
|
||||
Use Node.js `>=22.0.0` and Bun `1.3.13` or newer for source builds.
|
||||
|
||||
@@ -436,59 +368,24 @@ bun run build
|
||||
node dist/cli.mjs
|
||||
```
|
||||
|
||||
Helpful commands:
|
||||
Day-to-day commands:
|
||||
|
||||
- `bun run dev`
|
||||
- `bun test`
|
||||
- `bun run test:coverage`
|
||||
- `bun run security:pr-scan -- --base origin/main`
|
||||
- `bun run smoke`
|
||||
- `bun run doctor:runtime`
|
||||
- `bun run verify:privacy`
|
||||
- focused `bun test ...` runs for the areas you touch
|
||||
- `bun run dev` — build and launch from source
|
||||
- `bun test` — full unit suite (Bun's built-in runner)
|
||||
- `bun test path/to/file.test.ts` — focused runs for the areas you touch
|
||||
- `bun run test:coverage` — coverage to `coverage/lcov.info` plus a visual report at `coverage/index.html` (`bun run test:coverage:ui` rebuilds just the UI)
|
||||
- `bun run smoke` — smoke checks
|
||||
- `bun run doctor:runtime`, `bun run verify:privacy`, `bun run security:pr-scan -- --base origin/main`
|
||||
|
||||
## Testing And Coverage
|
||||
Focused suites: `bun run test:provider`, `bun run test:provider-recommendation`.
|
||||
|
||||
OpenClaude uses Bun's built-in test runner for unit tests.
|
||||
|
||||
Run the full unit suite:
|
||||
|
||||
```bash
|
||||
bun test
|
||||
```
|
||||
|
||||
Generate unit test coverage:
|
||||
|
||||
```bash
|
||||
bun run test:coverage
|
||||
```
|
||||
|
||||
Open the visual coverage report:
|
||||
|
||||
```bash
|
||||
open coverage/index.html
|
||||
```
|
||||
|
||||
If you already have `coverage/lcov.info` and only want to rebuild the UI:
|
||||
|
||||
```bash
|
||||
bun run test:coverage:ui
|
||||
```
|
||||
|
||||
Use focused test runs when you only touch one area:
|
||||
|
||||
- `bun run test:provider`
|
||||
- `bun run test:provider-recommendation`
|
||||
- `bun test path/to/file.test.ts`
|
||||
|
||||
Recommended contributor validation before opening a PR:
|
||||
Recommended validation before opening a PR:
|
||||
|
||||
- `bun run build`
|
||||
- `bun run smoke`
|
||||
- `bun run test:coverage` for broader unit coverage when your change affects shared runtime or provider logic
|
||||
- `bun run test:coverage` when your change affects shared runtime or provider logic
|
||||
- focused `bun test ...` runs for the files and flows you changed
|
||||
|
||||
Coverage output is written to `coverage/lcov.info`, and OpenClaude also generates a git-activity-style heatmap at `coverage/index.html`.
|
||||
## Repository Structure
|
||||
|
||||
- `src/` - core CLI/runtime
|
||||
@@ -500,7 +397,7 @@ Coverage output is written to `coverage/lcov.info`, and OpenClaude also generate
|
||||
|
||||
## VS Code Extension
|
||||
|
||||
The repo includes a VS Code extension in [`vscode-extension/openclaude-vscode`](vscode-extension/openclaude-vscode) for OpenClaude launch integration, provider-aware Control Center, in-editor chat, theme support, and optional **Microsoft Foundry / Azure OpenAI** configuration (endpoint, API version, deployment, API key via Secret Storage) injected into launched terminals. See that folder’s [README](vscode-extension/openclaude-vscode/README.md).
|
||||
The repo includes a VS Code extension in [`vscode-extension/openclaude-vscode`](vscode-extension/openclaude-vscode) for OpenClaude launch integration, provider-aware Control Center, in-editor chat, theme support, and optional **Microsoft Foundry / Azure OpenAI** configuration (endpoint, API version, deployment, API key via Secret Storage) injected into launched terminals. See that folder's [README](vscode-extension/openclaude-vscode/README.md).
|
||||
|
||||
## Security
|
||||
|
||||
@@ -515,15 +412,9 @@ If you believe you found a security issue, see [SECURITY.md](SECURITY.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome.
|
||||
|
||||
For larger changes, open an issue first so the scope is clear before implementation. Helpful validation commands include:
|
||||
|
||||
- `bun run build`
|
||||
- `bun run test:coverage`
|
||||
- `bun run smoke`
|
||||
- focused `bun test ...` runs for files and flows you changed
|
||||
|
||||
Contributions are welcome. For larger changes, open an issue first so the
|
||||
scope is clear before implementation. See [Development](#development) for the
|
||||
build, test, and pre-PR validation commands.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
# Agent Routing and Step Limits
|
||||
|
||||
OpenClaude can route different agents to different models, and custom agents
|
||||
can cap how many tool-use steps they may execute. Both features live in
|
||||
settings and agent frontmatter — no code changes required.
|
||||
|
||||
## Agent step limits
|
||||
|
||||
Custom agents can define `maxSteps` as a positive integer to cap how many
|
||||
tool-use steps a sub-agent may execute. When the limit is reached, OpenClaude
|
||||
stops additional tool calls and asks the sub-agent for a concise final summary
|
||||
covering completed work, findings, remaining tasks, and whether another run is
|
||||
needed. Omitting `maxSteps`, or setting it to an invalid value such as `0` or
|
||||
malformed input, preserves the default unlimited behavior.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: bounded-researcher
|
||||
description: Use for focused research with bounded tool use
|
||||
maxSteps: 8
|
||||
---
|
||||
|
||||
You are a focused research agent.
|
||||
```
|
||||
|
||||
## Agent routing
|
||||
|
||||
OpenClaude can route different agents to different models through
|
||||
settings-based routing. This is useful for cost optimization or splitting work
|
||||
by model strength.
|
||||
|
||||
Add to `~/.openclaude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agentModels": {
|
||||
"deepseek-v4-flash": {
|
||||
"base_url": "https://api.deepseek.com/v1",
|
||||
"api_key": "sk-your-key"
|
||||
},
|
||||
"zai-default": {
|
||||
"model": "glm-5.2",
|
||||
"base_url": "https://api.z.ai/api/coding/paas/v4",
|
||||
"api_key": "sk-your-key"
|
||||
},
|
||||
"gpt-4o": {
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-your-key"
|
||||
}
|
||||
},
|
||||
"agentRouting": {
|
||||
"Explore": "deepseek-v4-flash",
|
||||
"Plan": "gpt-4o",
|
||||
"general-purpose": "gpt-4o",
|
||||
"frontend-dev": "zai-default",
|
||||
"default": "gpt-4o"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When no routing match is found, the global provider remains the fallback.
|
||||
|
||||
`agentRouting` values and explicit Agent tool `model` overrides match keys in
|
||||
`agentModels`. By default, that key is also the model string sent to the
|
||||
provider. Set `agentModels.<key>.model` when you want a local route key such
|
||||
as `zai-default` to call a different provider model name such as `glm-5.2`.
|
||||
|
||||
> **Note:** `/provider` changes the global/parent provider for your current
|
||||
> session. `agentModels` and `agentRouting` are specifically for configuring
|
||||
> per-agent provider overrides while keeping the parent session unchanged.
|
||||
|
||||
> **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep
|
||||
> this file private and do not commit it to version control.
|
||||
|
||||
**Model-only routes (same provider):** Omit `base_url` and `api_key` to run an
|
||||
agent on a different model using your *current* provider's endpoint and key —
|
||||
no credential duplication:
|
||||
|
||||
```json
|
||||
{
|
||||
"agentModels": {
|
||||
"mini": { "model": "gpt-5-mini" }
|
||||
},
|
||||
"agentRouting": {
|
||||
"verification": "mini"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Built-in agents are routable by their type name.** Useful keys:
|
||||
`verification` (the read-only auditor that runs before completion), `Explore`,
|
||||
and `Plan`. For example, `"agentRouting": { "verification": "mini" }` runs the
|
||||
verifier on `gpt-5-mini` while your main session stays on its model. Absent
|
||||
any entry, the verifier inherits the main-loop model.
|
||||
|
||||
## GitHub Copilot sub-agent optimization
|
||||
|
||||
When `CLAUDE_CODE_USE_GITHUB=1`, OpenClaude serializes sub-agent execution to
|
||||
reduce GitHub Copilot Premium Request consumption. Default behavior is
|
||||
`GITHUB_COPILOT_MAX_SUBAGENTS=1` (synchronous, one sub-agent at a time).
|
||||
Tuning vars (all optional):
|
||||
|
||||
| Var | Effect |
|
||||
|---|---|
|
||||
| `GITHUB_COPILOT_MAX_SUBAGENTS=0` | Suppress sub-agents entirely (sub-agents throw an error). |
|
||||
| `GITHUB_COPILOT_MAX_SUBAGENTS=1` | Force synchronous execution. **Default.** |
|
||||
| `GITHUB_COPILOT_MAX_SUBAGENTS=2..10` | Parsed/clamped but not enforced differently from `=1` (any positive cap = synchronous). |
|
||||
| `GITHUB_COPILOT_ALLOW_SUBAGENTS=1` | Re-enable parallel/background sub-agents, overriding the cap. |
|
||||
| `GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS=1` | Force synchronous execution regardless of cap. |
|
||||
| `GITHUB_COPILOT_OPTIMIZATION_DISABLED=1` | Disable all of the above; sub-agents run as before this feature. |
|
||||
|
||||
The `is_async` field reported in the `tengu_agent_tool_selected` event and the
|
||||
agent metadata reflects the final execution mode (i.e., `false` when
|
||||
synchronous is forced). See `.env.example` for the full descriptions.
|
||||
|
||||
For best results, use models with strong tool/function calling support.
|
||||
@@ -0,0 +1,61 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 580 94" role="img" aria-label="OpenClaude — Open terminal for any LLM">
|
||||
<!-- Startup wordmark (src/constants/brand.ts) as pure rects: no font
|
||||
dependence, crisp at any size. OPEN light green, CLAUDE brand green,
|
||||
mirroring the TUI shimmer/brand split. Regenerate via git history
|
||||
script if the brand wordmark changes. -->
|
||||
<rect x="10" y="0" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="66" y="0" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="122" y="0" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="178" y="0" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="220" y="0" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="248" y="0" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="304" y="0" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="374" y="0" width="28" height="12.5" fill="#4eba65"/>
|
||||
<rect x="416" y="0" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="444" y="0" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="472" y="0" width="28" height="12.5" fill="#4eba65"/>
|
||||
<rect x="528" y="0" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="10" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="38" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="66" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="94" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="122" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="178" y="12" width="28" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="220" y="12" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="248" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="304" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="360" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="388" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="416" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="444" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="472" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="500" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="528" y="12" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="10" y="24" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="38" y="24" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="66" y="24" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="122" y="24" width="28" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="178" y="24" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="206" y="24" width="28" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="248" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="304" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="360" y="24" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="416" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="444" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="472" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="500" y="24" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="528" y="24" width="28" height="12.5" fill="#4eba65"/>
|
||||
<rect x="10" y="36" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="66" y="36" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="122" y="36" width="42" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="178" y="36" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="220" y="36" width="14" height="12.5" fill="#86dc9a"/>
|
||||
<rect x="248" y="36" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="304" y="36" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="360" y="36" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="388" y="36" width="14" height="12.5" fill="#4eba65"/>
|
||||
<rect x="416" y="36" width="42" height="12.5" fill="#4eba65"/>
|
||||
<rect x="472" y="36" width="28" height="12.5" fill="#4eba65"/>
|
||||
<rect x="528" y="36" width="42" height="12.5" fill="#4eba65"/>
|
||||
<text x="290.0" y="80" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15" letter-spacing="0.22em" fill="#8b949e">OPEN TERMINAL FOR ANY LLM</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.0 KiB |
@@ -0,0 +1,39 @@
|
||||
# Headless gRPC Server
|
||||
|
||||
OpenClaude can be run as a headless gRPC service, allowing you to integrate
|
||||
its agentic capabilities (tools, bash, file editing) into other applications,
|
||||
CI/CD pipelines, or custom user interfaces. The server uses bidirectional
|
||||
streaming to send real-time text chunks, tool calls, and request permissions
|
||||
for sensitive commands.
|
||||
|
||||
## 1. Start the gRPC server
|
||||
|
||||
Start the core engine as a gRPC service on `localhost:50051`:
|
||||
|
||||
```bash
|
||||
npm run dev:grpc
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|-----------|-------------|------------------------------------------------|
|
||||
| `GRPC_PORT` | `50051` | Port the gRPC server listens on |
|
||||
| `GRPC_HOST` | `localhost` | Bind address. Use `0.0.0.0` to expose on all interfaces (not recommended without authentication) |
|
||||
|
||||
## 2. Run the test CLI client
|
||||
|
||||
A lightweight CLI client is provided that communicates exclusively over gRPC.
|
||||
It acts just like the main interactive CLI, rendering colors, streaming
|
||||
tokens, and prompting you for tool permissions (y/n) via the gRPC
|
||||
`action_required` event.
|
||||
|
||||
In a separate terminal, run:
|
||||
|
||||
```bash
|
||||
npm run dev:grpc:cli
|
||||
```
|
||||
|
||||
> **Note:** The gRPC definitions are located in `src/proto/openclaude.proto`.
|
||||
> You can use this file to generate clients in Python, Go, Rust, or any other
|
||||
> language.
|
||||
Reference in New Issue
Block a user