mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-20 09:09:35 +02:00
docs(copilot): document GitHub Copilot CLI in full
- New docs/copilot-integration.md in the shape of the other CLI guides: install and identity probe, authentication (keychain vs plain-text config.json, COPILOT_GITHUB_TOKEN), what Codeman wires up (Run button --yolo and its clamp, model, resume, continue, --name rule), BYOK custom endpoints, terminal behaviour (drag selection, wheel and touch), the codeman agent verbs (ready mark, read), plan usage, Docker, Remote SSH, what is deliberately not wired, known gaps. - Agent-CLIs wiki: the eleven-modes table, a GitHub Copilot CLI section, the env prefix row, the feature-comparison rows and the status endpoint list. - README, Home, FAQ, Core Concepts, Docker Cases, Remote SSH, Contributing, The Dashboard and Custom Model Endpoints: mode lists and counts; CLAUDE.md: stack line, SessionMode, prefixes, resolver list, external-CLI notes and the plan-usage source; api-reference MCP target wording; the env allowlist error message names COPILOT_*.
This commit is contained in:
1 parent
89a82c68d1
commit
5b77c271b0
14 files changed
+276
-39
No files matched your search
@@ -1139,7 +1139,7 @@ Copies MCP servers between the agent CLIs' own user-level config files (`docs/cl
|
||||
Result (`data`):
|
||||
|
||||
- `applied` — `false` for the dry run.
|
||||
- `targets[]` — one per enabled CLI that declares an MCP config, plus GitHub Copilot CLI (`id: "copilot"`, a sync-only target that is not a run mode): `id`, `label`, `file`, `status`, `error?`, `servers` (names it already has), `added` (names added, or that would be), `skipped` (names its dialect cannot express, e.g. SSE for Codex and Antigravity).
|
||||
- `targets[]` — one per enabled CLI that declares an MCP config, including GitHub Copilot CLI (`id: "copilot"`; it is a run mode that declares its own `mcpConfig`, and a sync-only target takes its place only while that run mode is disabled): `id`, `label`, `file`, `status`, `error?`, `servers` (names it already has), `added` (names added, or that would be), `skipped` (names its dialect cannot express, e.g. SSE for Codex and Antigravity).
|
||||
- `status`: `ok`; `absent` (not installed and no config file, so not read or created); `skipped` (the CLI's relocation env var, e.g. `CODEX_HOME`, is set to a relative path in the server's environment, so its file cannot be located safely and is neither read nor written); `unreadable` (the file exists but cannot be parsed safely, so it is not written); `failed` (a read or write error, the file may be unchanged).
|
||||
- `error` says why a target is not `ok`. A parse failure is reported by position only (`not valid TOML (line 3, column 21)`, `not valid JSON`), never with text from the file.
|
||||
- `file` honours each CLI's own relocation env var as the server process sees it (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME`, and `COPILOT_HOME` for the sync-only Copilot CLI); see `docs/cli-registry.md`.
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
# GitHub Copilot CLI sessions
|
||||
|
||||
Codeman can drive [GitHub Copilot CLI](https://github.com/github/copilot-cli) (`copilot`,
|
||||
npm `@github/copilot`) as a session backend, alongside Claude Code, OpenCode, Codex, Gemini,
|
||||
Antigravity, Pi, Grok, DeepSeek Harness and OMP. `copilot` is a run mode: its own PTY, its
|
||||
own tmux session, its own tab identity (purple, a drawn mark rather than GitHub's logo). It is
|
||||
not a location overlay like Docker or remote-SSH cases, and it is not a web tab.
|
||||
|
||||
Everything here was measured against Copilot CLI 1.0.94 and 1.0.95 inside tmux. The entry
|
||||
itself is registry data (`src/config/cli-registry/stock.ts`); see
|
||||
[`cli-registry.md`](./cli-registry.md#github-copilot-cli) for the field-by-field reference.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install -g @github/copilot
|
||||
```
|
||||
|
||||
CLI management (Settings → Agents & CLIs) can run exactly that for you. Codeman resolves the
|
||||
binary from the server's PATH and the usual npm/nvm prefixes, then runs `copilot --version`
|
||||
and accepts it only if the output says `GitHub Copilot CLI <x.y.z>`. A bare `copilot` on PATH
|
||||
that answers anything else is ignored. Check what it resolved:
|
||||
|
||||
```bash
|
||||
curl -s localhost:3000/api/copilot/status | jq
|
||||
# { "available": true, "path": "/home/you/.local/bin", "version": "1.0.95" }
|
||||
```
|
||||
|
||||
## Authenticate
|
||||
|
||||
Codeman never logs Copilot in or stores its credentials.
|
||||
|
||||
- **Interactive.** Run `copilot` once and use `/login` (or `copilot login`), or do it inside a
|
||||
Codeman tab. The token goes to the OS keychain when one is available.
|
||||
- **Headless server.** There is no keychain on a service, so Copilot offers to keep the token
|
||||
as **plain text in `~/.copilot/config.json`** (`authTokens`). That is where it ends up when you
|
||||
accept. To keep a token out of a file, set `COPILOT_GITHUB_TOKEN` in the service environment;
|
||||
Copilot reads it first, then `GH_TOKEN`, then `GITHUB_TOKEN`.
|
||||
- **Per-session override.** `COPILOT_*` is the only prefix the env allowlist admits for
|
||||
Copilot. `GH_TOKEN` and `GITHUB_TOKEN` are deliberately **not** accepted as per-session
|
||||
overrides: the allowlist is one global list with no mode context, so admitting them would
|
||||
make them settable on every session. Use `COPILOT_GITHUB_TOKEN`.
|
||||
- **No GitHub sign-in is needed** when a session points at your own endpoint (below).
|
||||
|
||||
## What Codeman wires up
|
||||
|
||||
| Thing | Behaviour |
|
||||
| --- | --- |
|
||||
| Launch | `copilot`, in Copilot's own Manual Approval mode. |
|
||||
| Run button | `copilot --yolo` (allow every tool, path and URL), like the other CLIs' bypass switches, so an unattended session never stops on an approval. |
|
||||
| Permission clamp | `allowAll` is a `privilegedParam`. A multi-user owner without the bypass grant has it forced back to `false`; an absent config is never materialized (a bare `copilot` is already safe). `COPILOT_HOME`, `COPILOT_ALLOW_ALL`, `COPILOT_PROVIDER_*` and `COPILOT_MODEL` are privileged env keys. |
|
||||
| Model | `--model <id>` from the Run menu / Session Options. |
|
||||
| Resume | `--resume <id>` from Past Sessions. The id (or name) must be one plain word starting with a letter or digit: `--resume`'s value is optional, so `--resume --yolo` would otherwise make `--yolo` its own flag and bypass the clamp. |
|
||||
| Continue | `--continue` on a respawn of a session that has none to resume. |
|
||||
| Name | The tab's name is passed as `--name <tab name>`, so Copilot's own session list reads like your tabs. Copilot refuses `--name` with `--resume`/`--continue`, so it is dropped there and a resumed session keeps its original name. |
|
||||
| Working / idle | The footer. A turn shows `◉ Working esc edit prompt` (the dot alternates `◉`/`◎`); the composer is the `❯` between two rules. A tool waiting for approval replaces the composer and reads as idle. |
|
||||
| Model detection | The right-hand field of the footer's last row, at rest and mid-turn. |
|
||||
| Status probe | `GET /api/copilot/status`, plus an entry in the CLI-installed probes and `codeman doctor`. |
|
||||
| MCP | The entry declares `mcpConfig` (`~/.copilot/mcp-config.json`, dialect `copilot-json`, relocated by `COPILOT_HOME`), so [MCP server sync](./cli-registry.md) treats it as a target and a source. `copilot mcp disable` is honoured (read from `settings.json`, never written). |
|
||||
| Docker | The agent image installs `@github/copilot`. No credential directory is seeded (see below). |
|
||||
|
||||
### Your own endpoint (BYOK)
|
||||
|
||||
With custom model endpoints on, a saved endpoint is offered in the Run menu for Copilot and
|
||||
launches straight onto it (no restart; the env is applied before the process starts):
|
||||
|
||||
| Codeman field | Variable |
|
||||
| --- | --- |
|
||||
| base URL (+ `/v1`) | `COPILOT_PROVIDER_BASE_URL` |
|
||||
| key | `COPILOT_PROVIDER_API_KEY` |
|
||||
| model | `COPILOT_MODEL` |
|
||||
|
||||
`COPILOT_PROVIDER_TYPE` is not set: it defaults to `openai`, which is what a Codeman custom
|
||||
endpoint is (llama.cpp, vLLM, Ollama). All of these are privileged env keys.
|
||||
|
||||
Checked at the CLI level against a local OpenAI-compatible endpoint (1.0.95): it posted to
|
||||
`/v1/chat/completions` with the key and the model name, needed no GitHub sign-in, and
|
||||
`--resume <id> --model <m>` / `--continue --model <m>` resumed earlier sessions. Tool calls
|
||||
through a custom endpoint were not exercised. Only keys are persisted (never values).
|
||||
|
||||
## Terminal behavior
|
||||
|
||||
Copilot is an alternate-screen TUI with mouse tracking on, so it needed one non-default
|
||||
decision, the same one OpenCode needed:
|
||||
|
||||
- **Selection.** Left in, xterm reports a plain drag to the TUI instead of selecting, so
|
||||
Auto Copy and copy-on-select silently did nothing (only Shift+drag selected). The entry is
|
||||
`altScreen: 'strip-mux-and-mouse'`: the tracking DECSETs are stripped under tmux, a drag is
|
||||
a local selection, and clicks still reach Copilot through the browser's hand-encoded tap
|
||||
(`cliMouseTracking` is published as the server strips).
|
||||
- **Wheel and touch.** Stripping the DECSETs also stops xterm encoding the wheel, so
|
||||
`_shouldForwardWheelToApp` forwards it by hand as SGR reports while Copilot is tracking the
|
||||
mouse; a phone swipe goes through the same gate. Shift+wheel scrolls Codeman's local
|
||||
history. If the tracking flag is stale after a server restart, the gesture falls back to
|
||||
PageUp/PageDown rather than going dead.
|
||||
- **Keys.** Keystrokes from `tmux send-keys` and `POST /api/sessions/:id/input` reach the
|
||||
composer; Shift+Enter inserts a newline; shell tool calls complete inside tmux
|
||||
(github/copilot-cli#4180 and #4223 report both failing on 1.0.70 to 1.0.74; neither
|
||||
reproduces on 1.0.94).
|
||||
- **Scrollbar.** Copilot draws a `┃` gutter at the right edge of every row; the response
|
||||
reader strips it.
|
||||
|
||||
## `codeman agent` verbs
|
||||
|
||||
The three `CODEMAN_*` variables are exported into every pane, so the
|
||||
[session-to-session verbs](../README.md#codeman-agent--session-to-session-verbs-in-every-cli-mode)
|
||||
work from inside a Copilot tab and against Copilot workers:
|
||||
|
||||
- `spawn` waits for the composer. The ready mark is the footer hint `/ commands · ? help`, **not**
|
||||
`❯`: the folder-trust dialog draws `❯ 1. Yes`, so the glyph would call a worker ready while it
|
||||
is still asking whether to trust the folder. An untrusted folder therefore makes `spawn`
|
||||
warn that the composer was not seen instead of claiming ready.
|
||||
- `send --wait` resolves on `idle`. `--until stop` is refused (`400`, "no Claude Code hooks")
|
||||
like every hook-less mode; use `idle`, `exit` or a `--match` marker.
|
||||
- `read` returns the last answer. Copilot's output stream is absolute cursor moves rather
|
||||
than lines, so the route reads the pane's **visible screen** (tmux `capture-pane`) and cuts it
|
||||
with a per-CLI pane dialect (`src/web/response-viewer-transcript.ts`): `❯ <prompt> HH:MM`,
|
||||
`● <answer>` with indented continuation, and the cwd / `Session: N AIC used` row, composer,
|
||||
footer and scrollbar as chrome. Everything before the first prompt (banner, trust dialog) is
|
||||
dropped, so a session that has not been asked anything answers nothing.
|
||||
- `interrupt` sends a bare ESC; `rm` refuses itself.
|
||||
|
||||
## Plan usage
|
||||
|
||||
The header chip gets a **Copilot** row with one `mo` window: the calendar-month premium-request
|
||||
quota. The tooltip adds the counts and the reset date.
|
||||
|
||||
- **Source.** `GET https://api.github.com/copilot_internal/user` →
|
||||
`quota_snapshots.premium_interactions` (`entitlement`, `remaining`, `percent_remaining`;
|
||||
`quota_reset_date_utc`). `chat` and `completions` report `unlimited: true` and are ignored. It
|
||||
is the quota the editors show, but it is **not part of GitHub's documented REST API**.
|
||||
- **When.** Every 10 minutes from the host, read-only, only while the CLI is installed, a
|
||||
token resolves and plan-usage display is on (turning the chip off stops the request).
|
||||
- **Token.** `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`, then the signed-in user's
|
||||
`authTokens` entry in `<COPILOT_HOME or ~/.copilot>/config.json` (github.com sign-ins only).
|
||||
It is sent only to api.github.com over HTTPS with redirects refused, and is never logged or
|
||||
put in an error.
|
||||
- **Failure.** Offline, 401, a changed shape or an unlimited plan all yield no row. Overage
|
||||
is clamped to 100% in the bar and the real count is kept.
|
||||
|
||||
`copilot billing` exists only inside the TUI, so there is no CLI route to the same number.
|
||||
|
||||
## Docker cases
|
||||
|
||||
The agent image installs `@github/copilot`, and a docker case runs Copilot like any mode. **No
|
||||
credential directory is seeded**: without a keyring the sign-in token is plain text in
|
||||
`config.json`, and `CRED_STORES` (`src/docker-hosts.ts`) deliberately has no `.copilot` row.
|
||||
Sign in inside the container (`copilot login`), or set `COPILOT_GITHUB_TOKEN` for the session.
|
||||
|
||||
## Remote SSH cases
|
||||
|
||||
The launch line is built by the same registry path as a local session (the same flags, the same
|
||||
privileged-param clamp). A remote host needs its own `copilot` on its own PATH and its own
|
||||
sign-in. This path has unit coverage for the built command but was not exercised against a
|
||||
real remote host.
|
||||
|
||||
## What Codeman deliberately does NOT wire up
|
||||
|
||||
- **No login or token storage.** See Authenticate.
|
||||
- **No bypass inferred.** `--yolo` is sent only by the Run button's `allowAll`, never
|
||||
guessed from anything else, and is clamped for non-granted owners.
|
||||
- **No `--api-key`-style flag on the command line.** Secrets travel as environment variables
|
||||
through `tmux setenv`.
|
||||
- **No Claude-only features.** Auto-resume on a usage limit, the Approvals Inbox, Read My Mind,
|
||||
the Ralph tracker, subagent windows and the bundled agent skill are Claude-shaped.
|
||||
|
||||
## Known gaps
|
||||
|
||||
- `agent read` does not model tool-call rows: they open with the same `●` bullet and read as
|
||||
part of the answer.
|
||||
- `agent read` sees the visible screen, so an answer longer than one screen is its tail.
|
||||
- The plan-usage endpoint is undocumented and may change shape; the row then disappears.
|
||||
- Custom endpoints: tool calls through a BYOK endpoint were not exercised.
|
||||
- Remote SSH was not exercised against a real remote host.
|
||||
+69
-7
@@ -1,9 +1,9 @@
|
||||
# Agent CLIs
|
||||
|
||||
Codeman drives ten run modes: nine agent CLIs plus a plain shell. This page covers picking
|
||||
Codeman drives eleven run modes: ten agent CLIs plus a plain shell. This page covers picking
|
||||
one, setting it up, and the differences that actually change how you work.
|
||||
|
||||
## The ten modes
|
||||
## The eleven modes
|
||||
|
||||
| Mode | CLI | Get it |
|
||||
| -------------------- | ---------------------------- | ---------------------------------------------------------------------- |
|
||||
@@ -16,6 +16,7 @@ one, setting it up, and the differences that actually change how you work.
|
||||
| **Grok Build** | `grok` | [github.com/xai-org/grok-build](https://github.com/xai-org/grok-build) |
|
||||
| **DeepSeek Harness** | `dsh` | [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) |
|
||||
| **OMP** | `omp` | [github.com/can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) |
|
||||
| **GitHub Copilot** | `copilot` | [github.com/github/copilot-cli](https://github.com/github/copilot-cli) |
|
||||
| **Terminal / Shell** | your `$SHELL` | Already installed. |
|
||||
|
||||
Any combination works, including all of them. The run mode is chosen per session from the
|
||||
@@ -50,10 +51,10 @@ If a CLI is installed but a Run button for it never appears:
|
||||
precisely to avoid this; a hand-written plist or unit will not.
|
||||
3. Restart the server after installing a new CLI.
|
||||
|
||||
`pi`, `grok`, `omp` and `dsh` are additionally identity-probed rather than trusted by name:
|
||||
`pi`, `grok`, `omp`, `copilot` and `dsh` are additionally identity-probed rather than trusted by name:
|
||||
`pi` and `omp` are generic enough that something else on your PATH may answer to them,
|
||||
`grok` has npm squatters, and Debian ships an unrelated `dsh` (dancer's shell). Each has a
|
||||
status endpoint (`/api/grok/status`, `/api/deepseek/status`, `/api/omp/status`) that reports
|
||||
status endpoint (`/api/grok/status`, `/api/deepseek/status`, `/api/omp/status`, `/api/copilot/status`) that reports
|
||||
the path and version that actually resolved, so a misresolution is visible rather than
|
||||
presenting as "the mode just does not work".
|
||||
|
||||
@@ -69,9 +70,9 @@ output. The other CLIs expose no equivalent.
|
||||
| Respawn cycling and unattended runs | Yes | Yes |
|
||||
| Cron jobs | Yes | Yes |
|
||||
| Docker cases, remote SSH cases | Yes | Yes |
|
||||
| Precise idle detection | Yes | Codex, Pi, OpenCode, OMP and Gemini: same screen check, via their own prompt and working line. DeepSeek: reports its end of turn itself. Antigravity and Grok: generic cues only, unreliable |
|
||||
| Precise idle detection | Yes | Codex, Pi, OpenCode, OMP, Copilot and Gemini: same screen check, via their own prompt and working line. DeepSeek: reports its end of turn itself. Antigravity and Grok: generic cues only, unreliable |
|
||||
| Auto-resume when a usage limit resets | Yes | No |
|
||||
| Plan usage chip | Yes | No |
|
||||
| Plan usage chip | Yes | Codex and GitHub Copilot (monthly premium requests); others no |
|
||||
| Approvals Inbox | Yes | DeepSeek and Codex as alerts (answer in the terminal); others no |
|
||||
| Read My Mind | Yes | No |
|
||||
| Ralph loop and its task tracker | Yes | No |
|
||||
@@ -262,6 +263,66 @@ an OMP session that had started a turn showed as working for good.
|
||||
|
||||
Guide: [`docs/omp-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/omp-integration.md).
|
||||
|
||||
### GitHub Copilot CLI
|
||||
|
||||
GitHub's `copilot`, installed with `npm install -g @github/copilot` (CLI management can run
|
||||
that for you). Codeman recognises it only when `--version` answers `GitHub Copilot CLI`, and
|
||||
`GET /api/copilot/status` reports the path and version that resolved.
|
||||
|
||||
**Signing in.** Codeman does not log it in: run `copilot` once and use `/login`, or sign in
|
||||
inside a Codeman tab. Copilot keeps the token in the OS keychain when there is one; a headless
|
||||
server has none, so it offers to save it as **plain text in `~/.copilot/config.json`**, which is
|
||||
what a service ends up with. To keep a token out of a file, give the service
|
||||
`COPILOT_GITHUB_TOKEN` (Copilot reads it first, then `GH_TOKEN`, `GITHUB_TOKEN`). The token is
|
||||
never copied into a [Docker case](Docker-Cases): sign in inside the container.
|
||||
|
||||
**Run button and permissions.** Run starts `copilot --yolo` (allow every tool, path and URL),
|
||||
the same bypass switch the other agent CLIs get, so an unattended session never stops on an
|
||||
approval. A multi-user user without the bypass grant gets a plain `copilot`, which is
|
||||
Copilot's own Manual Approval mode. Model, permission mode and the rest are also changeable
|
||||
inside its TUI.
|
||||
|
||||
**Options and resume.** The model picked in the Run menu goes as `--model`. A session from
|
||||
Past Sessions resumes with `--resume <id>`, and a respawn continues with `--continue`. The
|
||||
tab's name is passed as `--name`, so Copilot's own session list reads like your tabs;
|
||||
Copilot refuses `--name` together with `--resume`/`--continue`, so a resumed session simply
|
||||
keeps the name it had.
|
||||
|
||||
**Your own endpoint.** With [custom model endpoints](Custom-Model-Endpoints) on, a saved
|
||||
endpoint appears in the Run menu for Copilot. It is launched with Copilot's BYOK variables
|
||||
(`COPILOT_PROVIDER_BASE_URL` with the `/v1` an OpenAI route needs, `COPILOT_PROVIDER_API_KEY`,
|
||||
`COPILOT_MODEL`), needs no GitHub sign-in, and applies at launch with no restart.
|
||||
|
||||
**Working and idle.** A turn shows `◉ Working` in the footer, which is what Codeman reads;
|
||||
a tool waiting for your approval replaces the composer and reads as idle. The model name is
|
||||
read from the footer too. Copilot has no hooks, so the `stop` and `blocked` wait signals are
|
||||
not available: wait on `idle`, `exit` or an output marker.
|
||||
|
||||
**Selecting and scrolling.** Copilot turns mouse tracking on itself. Codeman strips that, so a
|
||||
plain drag selects text (and Auto Copy works) and clicks still reach Copilot. The wheel, and a
|
||||
swipe on a phone, scroll Copilot's own transcript; Shift+wheel scrolls Codeman's local history.
|
||||
|
||||
**Plan usage.** The header chip gains a **Copilot** row with one `mo` window: this month's
|
||||
premium requests used. The tooltip shows the counts (for example `1215 of 5000 requests`) and
|
||||
the reset date. It is read from GitHub's `copilot_internal/user` endpoint with Copilot's own
|
||||
token, every 10 minutes, only while Copilot is installed and signed in and the chip is on. That
|
||||
endpoint is not part of GitHub's documented API: if it fails or your plan is unlimited, the row
|
||||
is simply absent.
|
||||
|
||||
**MCP servers.** [MCP server sync](Settings-Reference) includes Copilot's
|
||||
`~/.copilot/mcp-config.json` (relocated by `COPILOT_HOME`), as a target and a source.
|
||||
|
||||
**From another agent.** The `codeman agent` verbs work from inside a Copilot tab and against
|
||||
Copilot workers: `spawn` waits for the composer (not the folder-trust dialog), `send --wait`
|
||||
resolves on `idle`, and `read` returns the last answer from the pane's visible screen. Tool-call
|
||||
rows are not modelled and read as part of the answer, and `--until stop` is refused as for
|
||||
every hook-less mode.
|
||||
|
||||
**Not available.** Auto-resume on a usage limit, the Approvals Inbox, Read My Mind and the
|
||||
Ralph tracker, as for the other non-Claude CLIs.
|
||||
|
||||
Guide: [`docs/copilot-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/copilot-integration.md).
|
||||
|
||||
### Terminal / Shell
|
||||
|
||||
A plain shell in a tmux session. No agent, no hooks, no idle detection.
|
||||
@@ -288,6 +349,7 @@ respawns. Which variables are accepted depends on the mode:
|
||||
| Grok | `GROK_*`, `XAI_*` |
|
||||
| DeepSeek | `DSH_*`, `DEEPSEEK_*` |
|
||||
| OMP | `OMP_*` |
|
||||
| Copilot | `COPILOT_*` (a token goes in `COPILOT_GITHUB_TOKEN`; `GH_TOKEN` and `GITHUB_TOKEN` are not accepted as per-session overrides) |
|
||||
|
||||
Anything outside the allowlist is rejected at the schema. This is intentional: the allowlist
|
||||
is one global list, so widening it for one CLI widens it for all of them. In multi-user mode
|
||||
@@ -303,7 +365,7 @@ into the case's `.claude/settings.local.json` so that `/model` keeps working.
|
||||
|
||||
- **Claude Code** if you want every Codeman feature. Unattended overnight runs, usage-limit
|
||||
auto-resume, the Approvals Inbox, and subagent visualization all assume it.
|
||||
- **Codex, OpenCode, Gemini, Antigravity, Grok, OMP** when you prefer that agent or that
|
||||
- **Codex, OpenCode, Gemini, Antigravity, Grok, OMP, GitHub Copilot** when you prefer that agent or that
|
||||
model. You get the session layer, respawn, cron, Docker, and remote SSH; you do not get the
|
||||
hook-driven features (Codex dialogs still raise the red alert and an alert-only inbox card,
|
||||
see [Codex](#codex) above).
|
||||
|
||||
@@ -120,7 +120,7 @@ Conventions for wiki pages:
|
||||
- Images are referenced from the main repository over raw URLs rather than being copied into
|
||||
the wiki.
|
||||
- Say what the default is, especially when it is off. Most of Codeman is opt-in.
|
||||
- Label Claude-only behaviour every time it appears. Nine of the ten run modes are not
|
||||
- Label Claude-only behaviour every time it appears. Ten of the eleven run modes are not
|
||||
Claude.
|
||||
|
||||
## Conduct
|
||||
|
||||
@@ -59,7 +59,7 @@ A session carries state the case does not:
|
||||
## Run mode
|
||||
|
||||
The **run mode** is which CLI the session runs: `claude`, `opencode`, `codex`, `gemini`,
|
||||
`antigravity`, `pi`, `grok`, `deepseek`, `omp`, or `shell`. It is chosen at start and does not change afterwards; to
|
||||
`antigravity`, `pi`, `grok`, `deepseek`, `omp`, `copilot`, or `shell`. It is chosen at start and does not change afterwards; to
|
||||
switch, start another session.
|
||||
|
||||
Claude is the reference mode. Nine of the ten are not Claude, and a number of Codeman
|
||||
@@ -78,7 +78,7 @@ Where a case runs is **separate from** which CLI it runs. There are three locati
|
||||
| **Remote SSH** | A durable tmux server on the remote host, fronted by a local pane running `ssh`. See [Remote SSH Sessions](Remote-SSH-Sessions). |
|
||||
|
||||
This matters because it is a common source of confusion: Docker is **not** an eleventh run
|
||||
mode. All ten run modes work in all three locations. A case is docker-backed or
|
||||
mode. All eleven run modes work in all three locations. A case is docker-backed or
|
||||
ssh-backed; a session is claude or codex or shell.
|
||||
|
||||
**Web tabs** are the other thing that is not a session. A saved dashboard URL renders as a
|
||||
@@ -180,7 +180,7 @@ See [Hooks And Integrations](Hooks-And-Integrations).
|
||||
| --------------- | ---------------------------------------------------------------------------- |
|
||||
| **Case** | Named working directory. |
|
||||
| **Session** | One CLI in one tmux session. |
|
||||
| **Run mode** | Which CLI: claude, opencode, codex, gemini, antigravity, pi, grok, deepseek, omp, shell. |
|
||||
| **Run mode** | Which CLI: claude, opencode, codex, gemini, antigravity, pi, grok, deepseek, omp, copilot, shell. |
|
||||
| **Respawn** | Restarting the CLI on idle to keep an unattended run going. |
|
||||
| **Ralph loop** | An autonomous single-session task loop. |
|
||||
| **Orchestrator**| A phased plan driven across multiple agents. |
|
||||
@@ -191,6 +191,6 @@ See [Hooks And Integrations](Hooks-And-Integrations).
|
||||
## Read next
|
||||
|
||||
- [The Dashboard](The-Dashboard) - what the UI is showing you.
|
||||
- [Agent CLIs](Agent-CLIs) - the ten run modes in detail.
|
||||
- [Agent CLIs](Agent-CLIs) - the eleven run modes in detail.
|
||||
- [Keeping Agents Running](Keeping-Agents-Running) - respawn, idle detection, usage limits.
|
||||
- [`docs/architecture-invariants.md`](https://github.com/Ark0N/Codeman/blob/master/docs/architecture-invariants.md) - the mechanisms behind all of this, for contributors.
|
||||
@@ -58,11 +58,11 @@ another device starts from its own history). The default model keeps its own **D
|
||||
in both cases, and nothing is ever auto-chosen: the promoted row is simply the one under your
|
||||
thumb.
|
||||
|
||||
**For opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP, picking an entry launches
|
||||
**For opencode, Codex, Gemini, Pi, Grok, DeepSeek, OMP and GitHub Copilot, picking an entry launches
|
||||
straight onto the endpoint** — no restart, because the endpoint is applied before the
|
||||
session's process ever starts. **Claude still restarts the harness's process in place** —
|
||||
same tab, same conversation (`--resume`) — after a normal native launch, since that restart
|
||||
is far less jarring for Claude than for the other seven, whose own TUI can fully
|
||||
is far less jarring for Claude than for the others, whose own TUI can fully
|
||||
reinitialize on a restart. Either way, every supported harness reads its endpoint config at
|
||||
process start, never per turn, so there is no live hot-swap while a turn is running.
|
||||
|
||||
@@ -154,6 +154,7 @@ entry. "Launch anyway" is still there if you want to try regardless.
|
||||
|
||||
| Harness | Status |
|
||||
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **GitHub Copilot CLI** | Verified at the CLI level (1.0.95) against a local OpenAI-compatible endpoint: it posts to `/v1/chat/completions` with your key and model name and needs no GitHub sign-in. Tool calls through a custom endpoint were not exercised. |
|
||||
| **Claude Code, opencode, Pi, Grok, OMP** | Verified end-to-end against a real local server. |
|
||||
| **Codex** | Config is correct, and plain chat can work against a server that speaks the Responses API — but a real tool-call attempt comes back as inert text instead of running, so it's still not usable for real coding work. |
|
||||
| **Gemini** | Fails with an auth error gemini-cli raises once redirected. Unresolved; don't rely on it yet. |
|
||||
|
||||
@@ -4,7 +4,7 @@ Run a case inside its own container instead of directly on your host: for isolat
|
||||
reproducible toolchain, and for the ability to pick the whole environment up and move it to
|
||||
another machine.
|
||||
|
||||
A docker case is a **location overlay**, not a run mode. All ten run modes work inside a
|
||||
A docker case is a **location overlay**, not a run mode. All eleven run modes work inside a
|
||||
container. See [Core Concepts](Core-Concepts).
|
||||
|
||||
## One-time setup: the base image
|
||||
|
||||
+2
-2
@@ -23,8 +23,8 @@ stores, or refreshes your credentials.
|
||||
|
||||
### Which agent CLIs does it support?
|
||||
|
||||
Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness and
|
||||
OMP, plus a plain shell, chosen per session. Claude is the reference mode and a few features
|
||||
Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness,
|
||||
OMP and GitHub Copilot CLI, plus a plain shell, chosen per session. Claude is the reference mode and a few features
|
||||
are Claude-only; [Agent CLIs](Agent-CLIs) has the table.
|
||||
|
||||
### Does Codeman send my code or prompts anywhere?
|
||||
|
||||
+3
-3
@@ -6,7 +6,7 @@
|
||||
|
||||
Codeman runs your coding agents on your own machine and puts them behind one dashboard you
|
||||
can open from any device. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi,
|
||||
Grok, DeepSeek Harness, or OMP inside persistent tmux sessions, streams the real terminal to the browser, and keeps
|
||||
Grok, DeepSeek Harness, OMP, or GitHub Copilot CLI inside persistent tmux sessions, streams the real terminal to the browser, and keeps
|
||||
working while you are away from the keyboard: it re-prompts idle agents, resumes when a
|
||||
subscription limit resets, runs jobs on a schedule, and shows every background subagent
|
||||
live.
|
||||
@@ -33,7 +33,7 @@ codeman web # then open http://localhost:3000
|
||||
|
||||
**Already running it**
|
||||
|
||||
- [Agent CLIs](Agent-CLIs) - the ten run modes, their setup, and which features are Claude-only.
|
||||
- [Agent CLIs](Agent-CLIs) - the eleven run modes, their setup, and which features are Claude-only.
|
||||
- [Mobile Guide](Mobile-Guide) - phone and tablet use, QR login, the touch keyboard bar.
|
||||
- [Remote Access](Remote-Access) - Tailscale, Cloudflare tunnel, LAN plus password, QR login.
|
||||
- [Keeping Agents Running](Keeping-Agents-Running) - idle detection, respawn cycling, auto-resume on usage limits.
|
||||
@@ -127,7 +127,7 @@ codeman web # then open http://localhost:3000
|
||||
| OS | macOS or Linux. Windows works through WSL2. |
|
||||
| Node.js | 22 or newer. |
|
||||
| tmux | Required. Sessions live in tmux, which is what makes them survive restarts. |
|
||||
| An agent CLI | At least one of Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness, OMP. Plain shell sessions need none. |
|
||||
| An agent CLI | At least one of Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness, OMP, GitHub Copilot CLI. Plain shell sessions need none. |
|
||||
| Network | Binds to `127.0.0.1` by default. Reaching it from another device is a deliberate step: see [Remote Access](Remote-Access). |
|
||||
|
||||
Codeman is MIT licensed, self-hosted, and sends no telemetry. Everything runs on your
|
||||
|
||||
@@ -4,7 +4,7 @@ Point a case at another machine and the agent runs **there**, with the same dash
|
||||
mobile UI, and autonomy features. Your laptop becomes a window onto a session living on the
|
||||
remote host.
|
||||
|
||||
Like Docker, this is a **location overlay** on a case, not a run mode. All ten run modes
|
||||
Like Docker, this is a **location overlay** on a case, not a run mode. All eleven run modes
|
||||
work remotely. See [Core Concepts](Core-Concepts).
|
||||
|
||||
## Why bother
|
||||
|
||||
@@ -148,7 +148,7 @@ The right side of the header. Almost all of these are off until you enable them
|
||||
| CPU / MEM | On | Server resource use. Drawn as a compact pill by default; see Header Stats Style below. |
|
||||
| File Viewer | On | Toggles the file browser panel. |
|
||||
| Settings gear | Always on | App Settings. |
|
||||
| Plan usage chip | On, desktop only | Live Claude subscription usage. Claude-only, and needs its telemetry exporter, which the same setting installs. |
|
||||
| Plan usage chip | On, desktop only | Live Claude subscription usage (needs its telemetry exporter, which the same setting installs), plus a Codex row and a GitHub Copilot row (`mo`: this month's premium requests, with counts and the reset date in the tooltip) when those CLIs are signed in. |
|
||||
| Session Manager | Off | The full session list, live and historical. |
|
||||
| Approvals bell | Off | Cross-session queue of prompts waiting on a human. Appears only when the count is above zero. Never shown on phones. |
|
||||
| Read My Mind 🧠 | Off | Predicts your next prompt for this case. Claude-only. |
|
||||
|
||||
Reference in new issue
Block a user