{"id":50360271,"url":"https://github.com/codeweiz/chances-cli","last_synced_at":"2026-06-08T05:01:12.860Z","repository":{"id":360009746,"uuid":"1248026888","full_name":"codeweiz/chances-cli","owner":"codeweiz","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-06T02:11:34.000Z","size":6133,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T04:08:03.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeweiz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T04:58:52.000Z","updated_at":"2026-06-06T02:11:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codeweiz/chances-cli","commit_stats":null,"previous_names":["codeweiz/chances-cli"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/codeweiz/chances-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeweiz%2Fchances-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeweiz%2Fchances-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeweiz%2Fchances-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeweiz%2Fchances-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeweiz","download_url":"https://codeload.github.com/codeweiz/chances-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeweiz%2Fchances-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34048682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T01:05:10.293Z","updated_at":"2026-06-08T05:01:12.728Z","avatar_url":"https://github.com/codeweiz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chances-cli\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA Bun-first, multi-provider terminal coding agent.\u003c/strong\u003e\n  \u003cbr/\u003e\n  Pluggable adapters · enforced boundaries · interactive TUI · scriptable headless mode.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@chances-ai/cli\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/@chances-ai/cli?style=flat\u0026colorA=222222\u0026colorB=CB3837\u0026logo=npm\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/codeweiz/chances-cli/blob/main/LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-58A6FF?style=flat\u0026colorA=222222\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/codeweiz/chances-cli/blob/main/CHANGELOG.md\"\u003e\u003cimg alt=\"changelog\" src=\"https://img.shields.io/badge/changelog-keep%20a%20changelog-E05735?style=flat\u0026colorA=222222\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org\"\u003e\u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-3178C6?style=flat\u0026colorA=222222\u0026logo=typescript\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bun.sh\"\u003e\u003cimg alt=\"Bun\" src=\"https://img.shields.io/badge/runtime-Bun-F472B6?style=flat\u0026colorA=222222\u0026logo=bun\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.rust-lang.org\"\u003e\u003cimg alt=\"Rust\" src=\"https://img.shields.io/badge/native-Rust-DEA584?style=flat\u0026colorA=222222\u0026logo=rust\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e11 providers · 10 built-in tools · 7 slash commands · plugin API · 4-type memory · 0 boundary violations\u003c/strong\u003e\n\u003c/p\u003e\n\n---\n\n## Install\n\n**npm / bun / pnpm**\n\n```bash\nnpm  i -g @chances-ai/cli   # → `chances` binary on PATH\nbun  add -g @chances-ai/cli\npnpm add -g @chances-ai/cli\n```\n\n**Standalone binary** (zero dependencies — built with `bun build --compile`)\n\nPick a build from the [GitHub releases](https://github.com/codeweiz/chances-cli/releases/latest) page:\n`darwin-arm64` · `darwin-x64` · `linux-x64` · `linux-arm64` · `windows-x64.exe`.\n\n**From source** (contributors)\n\n```bash\ngit clone https://github.com/codeweiz/chances-cli \u0026\u0026 cd chances-cli\nbun install\nbun run dev          # interactive Ink chat (needs a TTY)\n```\n\nRequires Bun ≥ 1.3.14 for the dev flow; the published binary needs nothing.\n\n## Quick start\n\n```bash\n# 1. Health check — verifies runtime, config, credentials.\nchances doctor\n\n# 2. Mock provider works with no API key — useful for trying the loop offline.\nchances -p \"summarize package.json\" --json\n\n# 3. Real provider via env var.\nexport ANTHROPIC_API_KEY=sk-...\nchances                               # interactive Ink chat\nchances -p \"explain src/engine.ts\"    # one-shot\nchances -p \"/help\"                    # slash commands work in -p too\n```\n\nInside the interactive chat:\n\n```\n/help                # list all slash commands\n/model               # picker — switch models mid-session\n/provider list       # show configured providers\n/provider add kimi   # masked credential entry\n/mcp list            # MCP servers + status + tools\n/mcp restart fs      # tear down + reconnect one MCP server\n/mcp test github     # one-shot connect + list + dispose (debugging)\n/resume              # picker — switch to a saved session\n/compact             # summarize and shrink the conversation\n/clear               # empty the current turn list\n/logout \u003cprovider\u003e   # remove a stored credential\n```\n\n## What you get\n\n### Providers\n\n11 providers, dispatched data-driven by `ProviderEntry.api` — adding a new\nOpenAI-compatible vendor is one entry in `KNOWN_MODELS`.\n\n| Native (`@ai-sdk/*`) | OpenAI-compatible (`@ai-sdk/openai-compatible`) |\n|---|---|\n| `anthropic` `openai` `google` | `xai` `groq` `openrouter` `deepseek` `doubao` `minimax` `glm` `kimi` |\n\n### Built-in tools\n\n`read` · `write` · `edit` · `bash` · `grep` · `glob` · `diff` · `web_fetch` · `task` · `memory_save` · `memory_delete` · `memory_list`\n\nPlus any tool exposed by a configured **MCP server**, registered dynamically as\n`mcp__\u003cserver\u003e__\u003ctool\u003e`. Every tool — built-in, plugin, OR MCP-bridged — goes\nthrough the same `PermissionGate`. The default policy auto-allows\nreads/search/memory and prompts on write/shell/integration. MCP tools inherit\nthose categories via their schema annotations (`readOnlyHint` → file-read,\n`destructiveHint` → file-write, etc.). Per-tool overrides live in\n`\u003cworkspace\u003e/.chances/config.json`.\n\n### MCP servers (3.1)\n\nConfigure servers in `\u003cworkspace\u003e/.chances/config.json`:\n\n```jsonc\n{\n  \"mcp\": {\n    \"servers\": {\n      \"filesystem\": {\n        \"type\": \"stdio\",\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"]\n      },\n      \"weather\": {\n        \"type\": \"http\",\n        \"url\": \"https://example.com/mcp\",\n        \"headers\": { \"Authorization\": \"Bearer ${WEATHER_TOKEN}\" }\n      }\n    }\n  }\n}\n```\n\nEnv substitution supports `${VAR}` and `${VAR:-default}`. Project entries\nshadow user entries with the same name. Manage at runtime with\n`/mcp list | tools | resources | prompts | restart \u003cname\u003e | test \u003cname\u003e | remove \u003cname\u003e | add | login | logout`.\nThe `@modelcontextprotocol/sdk` package is an **optional peer dep** — when no\nservers are configured, it's never loaded (no cold-start cost).\n\n**Resources + prompts (v9.0.0).** Beyond tools, the agent consumes a server's\n**resources** and **prompts**:\n\n- **Prompts** become slash commands `/\u003cserver\u003e:\u003cprompt\u003e [args]` — invoking one\n  fetches the server's prompt and submits it as a turn.\n- **Resources** are reachable two ways: the model calls `mcp_list_resources` /\n  `mcp_read_resource`, or you reference one inline with `@\u003cserver\u003e:\u003curi\u003e`\n  (autocompleted; read and injected into your message).\n\nThe client advertises `roots` (the workspace path; disable with\n`\"mcp\": { \"advertiseRoots\": false }`). **MCP sampling is intentionally not\nadvertised** — letting a server drive your model is a cost + prompt-injection\nsurface, and neither claude-code nor oh-my-pi ships it.\n\n### Memory\n\n4-type frontmatter schema (`user` / `feedback` / `project` / `reference`)\nacross two scopes (`~/.chances/memory/` cross-project, `\u003cworkspace\u003e/.chances/memory/`\nproject-local). The model calls `memory_save` / `memory_delete` / `memory_list`\ndirectly; the agent's system prompt is auto-augmented with the relevant\nindexes and bodies subject to a 25 KiB per-scope budget.\n\n### Plugin API\n\n```ts\nimport { definePlugin } from \"@chances-ai/plugin-api\";\n\nexport default definePlugin({\n  name: \"my-plugin\",\n  onLoad(ctx) {\n    ctx.registerTool({ /* same Tool interface as built-ins */ });\n    ctx.registerSlashCommand({ name: \"ping\", run: () =\u003e \"pong\" });\n    ctx.registerHook(\"afterToolCall\", ({ name, ok }) =\u003e {\n      ctx.logger.info(`tool ${name} ${ok ? \"ok\" : \"failed\"}`);\n    });\n  },\n});\n```\n\nHooks: `beforePrompt` / `beforeToolCall` / `afterToolCall` / `afterResponse`.\nPlugin load failures roll back atomically — a buggy plugin can't leave the host\nin a half-initialized state.\n\n### Headless modes\n\n```bash\nchances -p \"\u003cprompt\u003e\"            # text mode (default)\nchances -p \"\u003cprompt\u003e\" --json     # one JSON envelope on stdout\nchances -p \"\u003cprompt\u003e\" --ndjson   # one event per line — pipe through jq\nchances --yes -p \"...\"           # auto-approve all permission prompts\n```\n\nExit codes are stable: `0` success · `1` unknown · `2` usage · `3` permission ·\n`4` provider · `5` tool · `130` cancelled. CI scripts can branch on them.\n\n## Configuration\n\nThree layers, later wins: global file → project file → env.\n\n| Path | Purpose |\n|---|---|\n| `~/.config/chances/config.json` | Cross-project defaults |\n| `\u003cworkspace\u003e/.chances/config.json` | Project overrides |\n| `~/.config/chances/auth.json` | Provider credentials (0600 on POSIX) |\n| Env vars | One-off / CI overrides |\n\nCommon env vars:\n\n```bash\nCHANCES_PROVIDER=anthropic\nCHANCES_MODEL=claude-opus-4-7\nCHANCES_MAX_TURNS=20         # agent loop budget (1..200)\nANTHROPIC_API_KEY=sk-...     # one per provider — see `chances doctor` for the full list\n```\n\n## Architecture\n\n```\napps/cli                 composition root — arg parsing, modes, exit codes\n  ├── commands/          chat, doctor, config, session, stats, discover, version\n  ├── modes/             text / json / ndjson renderers\n  └── slash/             8 first-party slash commands (use the same PluginContext as external plugins)\n\npackages/\n  ├── runtime            event bus, cancellation, logger, errors, model-selection\n  ├── config             load/merge/discover, AuthStore, permission policy\n  ├── ai                 ProviderAdapter port, registry, router, AI-SDK + OpenAI-compatible + mock adapters\n  ├── session            transcript persistence, resume, compact\n  ├── memory             frontmatter-typed store, three model-callable tools\n  ├── tools              ToolRegistry, PermissionGate (+ session positive-decision cache), 7 built-in tools\n  ├── plugin-api         definePlugin, PluginHost, hooks, slash dispatch\n  ├── mcp                MCP client (stdio + streamable HTTP), tool bridge, /mcp host, secret redactor\n  ├── core               AgentEngine — the loop (only depends on type imports of peer packages)\n  ├── tui                Ink chat + modal slot + 3 pickers (model/session/api-key)\n  ├── telemetry          usage/cost JSONL sink on the bus\n  └── native             JS facade over Rust crates (JS fallback today; native search lands when bench needs it)\n\ncrates/                  6 Rust crate skeletons (chances-{native,fs,pty,diff,ast,tokenize})\n```\n\nBoundaries are **CI-enforced** (`.dependency-cruiser.cjs`):\n`app → ui → domain → infra → native`, one-way only. As of 3.1.1: **314 modules, 0 violations**.\n\n## Status\n\n| Major | Theme | Status |\n|---|---|---|\n| **1.x** | Foundation — engine, tools, permission gate, Ink TUI, sessions, multi-provider | shipped 2026-05-25 |\n| **2.x** | Extensible dev tool — 11 providers, Memory v1, Router v1, plugin API, glob/grep/diff, stats, discover | shipped 2026-05-26 |\n| **3.0** | Interactive UX — slash commands, mid-session `/model`, runtime `/provider add`, modal pickers, autocomplete | shipped 2026-05-26 |\n| **3.0.1** | Pre-3.1 patch pass — diagnostic adapter errors, configurable `agent.maxTurns`, terminal exhaustion error, api-key redaction, codex review | shipped 2026-05-26 |\n| **3.1** | MCP client — `@chances-ai/mcp`, stdio + streamable HTTP, tool bridge, `/mcp` slash, session-cached permission gate, secret redactor, ANSI strip, collision detection, three rounds of codex review | shipped 2026-05-26 |\n| **3.1.1** | Release pipeline hardening — workspace-derived publish list, `publint` in CI verify, two shim scripts removed | shipped 2026-05-27 |\n| **3.2.1** | `web_fetch` (SSRF-defended URL fetcher, new `network-read` category) + `task` Subagent v1 (child engine, anti-recursion, shared gate); engine cancellation tightened + bus pair invariant restored | shipped 2026-05-27 |\n| **3.2.2** | PTY-backed bash via `crates/chances-pty` (first napi-rs crate, `portable-pty` + 2-wave kill + 300 ms drain budget); claude-code style 30 KB inline + persist-to-disk; ANSI passthrough at runtime, stripped at bash layer; JS spawn fallback; three rounds of codex review | shipped 2026-05-27 |\n| **3.2.3** | Native release pipeline — **single-package model** (all `chances-pty.\u003cplatform\u003e-\u003carch\u003e.node` shipped inside `@chances-ai/native`); ABI version sentinel auto-generated by `build.rs` from `CARGO_PKG_VERSION` (no hand-maintained literal); Windows file-lock staging to `~/.chances/natives/\u003cversion\u003e/` (immutable per `(version, filename)`, race-safe); CI `build_natives` matrix (5 native runners) with `Swatinem/rust-cache` + unconditional smoke; both `release_github` and `release_npm` gate on native matrix; macOS ad-hoc codesign + `--strict` verify; doctor reports loaded path + sentinel; two rounds of codex review (4 design + 3 impl MUST-FIX folded in) | shipped 2026-05-27 |\n| **3.3 / 3.4 / 3.5 / 3.6 / 3.7** | 3.3 agent catalogs (`.chances/agents/*.md`); 3.4 parallel + background subagents (`run_in_background: true`, bounded concurrency); 3.5 auto-compaction (threshold + idle + tool-output pruning); 3.6 OTel exporter (`@chances-ai/telemetry-otel`, OpenTelemetry GenAI semconv); 3.7 OAuth for MCP servers (Keychain / Secret Service / Credential Manager primary, 0o600 JSON fallback) | planned, ordered |\n| **3.x later → 5.x** | Shipped in order: worktree isolation (v4.1) → LSP tool (v5.0) → interactive PTY (v6.0/6.0.1) → Stable RPC / ACP host (v7.0) → approval-mode selector (v8.0) → **MCP resources + prompts (v9.0)**. Remaining: fork-from-parent subagent, `ToolContext.callId`, TUI xterm.js pane, MCP sampling (deferred). See `docs/STATUS.md` for the full per-item rationale + codex review verdicts. | shipping |\n\nSee [`docs/STATUS.md`](docs/STATUS.md) for the version-by-version breakdown,\n[`docs/ROADMAP.md`](docs/ROADMAP.md) for the long-form plan, and\n[`CHANGELOG.md`](CHANGELOG.md) for release-level changes.\n\n## Documentation\n\n- [`docs/PRD.md`](docs/PRD.md) — product definition + capability matrix.\n- [`docs/TECH_DESIGN.md`](docs/TECH_DESIGN.md) — architecture, patterns, the engine loop.\n- [`docs/PROJECT_STRUCTURE.md`](docs/PROJECT_STRUCTURE.md) — package contracts, public exports.\n- [`docs/ROADMAP.md`](docs/ROADMAP.md) — 1.x → 5.x plan.\n- [`docs/STATUS.md`](docs/STATUS.md) — what's shipped vs. pending, kept in sync with every release.\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — dev workflow, conventions, release process.\n- [`docs/ADR/`](docs/ADR) — architecture decision records.\n\n## Development\n\n```bash\nbun run check        # tsc project-reference typecheck across 25 packages (via Turbo)\nbun test             # unit + integration tests (514 tests at 3.1.1)\nbun run boundaries   # dependency-cruiser: enforce one-way layering\nbun run build:native # cargo build the Rust workspace\nbun run benchmark    # record performance baseline (cold start + grep/glob p95)\n```\n\n## Acknowledgments\n\nThe architecture draws from two excellent open-source projects (both MIT, both\nstudied clean-room):\n\n- [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono) — minimal multi-provider core, session-layer error recovery, model-resolver patterns.\n- [`can1357/oh-my-pi`](https://github.com/can1357/oh-my-pi) — native/extensible surface, plugin authoring shape, slash command UX.\n\nWe compare against Anthropic's [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\nfor terminal-coding-agent feature parity but ship a clean-room implementation.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeweiz%2Fchances-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeweiz%2Fchances-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeweiz%2Fchances-cli/lists"}