@makerbi/openclaude 0.23.0 → 0.24.0

package/README.md

@@ -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&amp;utm_medium=badge&amp;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&amp;utm_medium=badge&amp;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&amp;utm_medium=badge&amp;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.
 
@@ -13,7 +21,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
 
@@ -60,11 +68,11 @@ OpenClaude is also mirrored to GitLawb:
 
 ## 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
 
@@ -225,6 +233,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
@@ -246,6 +257,7 @@ Advanced and source-build guides:
 | OpenCode Go | `/provider` or env vars | $10/mo subscription for open models (13 models); uses `OPENCODE_API_KEY` via `https://opencode.ai/zen/go/v1`; shared key with OpenCode Zen |
 | Xiaomi MiMo | `/provider` or env vars | OpenAI-compatible API at `https://mimo.mi.com`; uses `MIMO_API_KEY` and defaults to `mimo-v2.5-pro` |
 | NEAR AI | `/provider` or env vars | Unified gateway (Claude, GPT, Gemini + TEE open models); uses `NEARAI_API_KEY` at `https://cloud-api.near.ai/v1` |
+| Cloudflare Workers AI | `/provider` or env vars | OpenAI-compatible API at `https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/v1`; uses `CLOUDFLARE_API_TOKEN`. Replace `<ACCOUNT_ID>` with your Cloudflare account id. |
 | Ollama | `/provider` or env vars | Local inference with no API key |
 | Atomic Chat | `/provider`, env vars, or `bun run dev:atomic-chat` | Local Model Provider; auto-detects loaded models |
 | Bedrock / Vertex / Foundry | env vars | Anthropic-family cloud routes; Vertex is for Claude on Vertex AI, not arbitrary Model Garden models |
@@ -259,6 +271,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
 
@@ -272,93 +308,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
-
-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.
+## Agents
 
-> **Note:** `api_key` values in `settings.json` are stored in plaintext. Keep this file private and do not commit it to version control.
+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:
 
-**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:
+- 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
 
-```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
 
@@ -383,42 +347,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.
-
-### 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.
+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`.
 
-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.
 
@@ -428,59 +365,24 @@ bun run build
 node dist/cli.mjs
 ```
 
-Helpful 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
-
-## Testing And Coverage
-
-OpenClaude uses Bun's built-in test runner for unit tests.
-
-Run the full unit suite:
-
-```bash
-bun test
-```
+Day-to-day commands:
 
-Generate unit test coverage:
+- `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`
 
-```bash
-bun run test:coverage
-```
+Focused suites: `bun run test:provider`, `bun run test:provider-recommendation`.
 
-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
@@ -492,7 +394,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
 
@@ -505,15 +407,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