Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Guidance for Claude Code (claude.ai/code) when working in this repository.
## Project identity

CodeDeck+ is a community-maintained continuation of CodeDeck Next: run coding
agents (Claude Code, OpenCode, DeepSeek Harness, Qwen Code) on a laptop/VPS ("the bridge") and drive them
agents (Claude Code, OpenCode, DeepSeek Harness, Qwen Code, Pi) on a laptop/VPS ("the bridge") and drive them
from an Android phone over end-to-end-encrypted Nostr. It started as a merge of
the two upstream projects (`codedeck-next-bridge`, `codedeck-next-mobile`) and
has since been rebuilt: the protocol, the bridge and the phone's core are Rust;
Expand Down Expand Up @@ -181,18 +181,19 @@ credentials (`--env` is for the agent's own paths, not its keys).
1. **`live fake`** — the scripted test agent: the driver protocol's own
plumbing, with no SDK and no model at all.
2. **`live <agent> --fake-model`** — a real agent (claude-code, opencode,
deepseek-harness, qwen-code) against a local model server
deepseek-harness, qwen-code, pi) against a local model server
(`packages/agent-host/tools/fake-model.mjs`). The session is real, the
model is not: each prompt is a scenario — `/tool` (a tool call; OpenCode
asks permission for it), `/question` (a question form), `/plan-approval`
and Pi ask permission for it), `/question` (a question form), `/plan-approval`
(a plan card), `/error` (an API failure), `/long` (a long answer and a
large context) — and anything else is echoed. Nothing reaches an account,
and CI runs the same thing for claude-code
(`src/drivers/claude/__tests__/claudeFakeModel.test.ts`).
and CI runs the same thing for claude-code and pi
(`src/drivers/claude/__tests__/claudeFakeModel.test.ts`,
`src/drivers/pi/__tests__/piFakeModel.test.ts`).
3. **A real model** — OpenCode on its free Zen models
(`--model opencode/cat-jam-free`) for fidelity, since only a real model
chooses its own tool arguments and writes prose. Everything else on
claude-code, deepseek-harness or qwen-code spends the account. The
claude-code, deepseek-harness, qwen-code or pi spends the account. The
commands for each tier are in the verify-changes skill.

### Tests
Expand Down Expand Up @@ -332,7 +333,7 @@ crates/protocol the phone wire: messages, total codec, kinds, ranges,
│ workspace, uploads, direct link, CLI.
│ │ stdio (driver protocol)
│ packages/agent-host Node: one driver per agent
│ (opencode, claude, deepseek, qwen, fake) around
│ (opencode, claude, deepseek, qwen, pi, fake) around
│ its SDK.
│ packages/vscode-extension installs a release's
│ bridge (sha256 baked in at release), runs it on
Expand Down
1 change: 1 addition & 0 deletions .claude/skills/verify-changes/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,7 @@ tiers, cheapest first — pick by what needs proving:
./codedeck live opencode --fake-model --prompt /question --prompt /long
./codedeck live deepseek-harness --fake-model --prompt /error
./codedeck live qwen-code --fake-model --prompt /tool
./codedeck live pi --fake-model --prompt /tool

# 3. A real model. Free on OpenCode's Zen models; anything else spends the account.
./codedeck live opencode --model opencode/cat-jam-free --prompt "Reply with exactly: ok"
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/agent-updates.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ jobs:
set -euo pipefail
title='Agent updates available'
# The agents' own packages, and the ACP types their drivers use.
packages='@anthropic-ai/claude-agent-sdk @opencode/client @opencode/cli @deepseek-ai/dsh @qwen-code/qwen-code @agentclientprotocol/sdk'
packages='@anthropic-ai/claude-agent-sdk @opencode/client @opencode/cli @deepseek-ai/dsh @qwen-code/qwen-code @earendil-works/pi-coding-agent @agentclientprotocol/sdk'
rows=''
for name in $packages; do
pinned=$(jq -r --arg n "$name" '(.dependencies + .devDependencies)[$n] // empty' packages/agent-host/package.json | sed 's/^[\^~]//')
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

# CodeDeck+

**Control coding agents (OpenCode, Claude Code, DeepSeek Harness, Qwen Code)
**Control coding agents (OpenCode, Claude Code, DeepSeek Harness, Qwen Code, Pi)
running on your laptop or VPS from your Android phone, over end-to-end
encrypted Nostr.** No accounts and no CodeDeck server: the phone and the bridge pair by
scanning a QR code and talk through ordinary Nostr relays — public ones, or
Expand Down Expand Up @@ -44,7 +44,8 @@ Pairing is a one-time QR scan; it survives restarts on both ends.
- [OpenCode](https://opencode.ai) (the default, installed on first start),
Claude Code, the
[DeepSeek Harness](https://www.deepseek.com/en/harness/) and
[Qwen Code](https://github.com/QwenLM/qwen-code) (installed from the phone
[Qwen Code](https://github.com/QwenLM/qwen-code) and
[Pi](https://github.com/earendil-works/pi) (installed from the phone
when chosen), picked per session — the protocol is agent-neutral, so another
agent is one driver away
([`docs/PROTOCOL.md`](docs/PROTOCOL.md#adding-an-agent))
Expand Down Expand Up @@ -247,6 +248,7 @@ the full runbook.
- [`docs/CLAUDE-CODE.md`](docs/CLAUDE-CODE.md) — Claude Code: sign-in, modes and models, the 1M window, gateways and provider profiles
- [`docs/DEEPSEEK.md`](docs/DEEPSEEK.md) — the DeepSeek Harness: API key, models and reasoning, gateways, MCP servers and plugins
- [`docs/QWEN.md`](docs/QWEN.md) — Qwen Code: install, OpenAI-compatible providers, its home, modes, MCP servers and extensions
- [`docs/PI.md`](docs/PI.md) — Pi: install, accounts and providers, its home, the permission gate and its tiers, MCP servers and packages
- [`docs/AGENT-CANDIDATES.md`](docs/AGENT-CANDIDATES.md) — which agents to add next and how
- [`.claude/skills/cut-release/SKILL.md`](.claude/skills/cut-release/SKILL.md) — the release runbook

Expand Down
4 changes: 2 additions & 2 deletions codedeck
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,7 @@ a Docker-less host:
--persona ID, --cwd DIR, --env K=V (agent paths and keys),
--timeout SECONDS (default 300), --no-sync
agents: claude-code, opencode, deepseek-harness,
qwen-code, and `fake` for the driver-protocol
qwen-code, pi, and `fake` for the driver-protocol
test agent
live <agent> --fake-model
Point the agent at a local model server instead
Expand Down Expand Up @@ -1290,7 +1290,7 @@ cmd_live() {
echo " background sub-agent or a late notification does" >&2
echo " CODEDECK_DEBUG_EVENTS=1 (via --env) logs every raw agent event the" >&2
echo " OpenCode driver received, with the session each names" >&2
echo "agents: claude-code, opencode, deepseek-harness, qwen-code, fake" >&2
echo "agents: claude-code, opencode, deepseek-harness, qwen-code, pi, fake" >&2
exit 2
;;
esac
Expand Down
2 changes: 2 additions & 0 deletions docs/AGENT-CANDIDATES.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ install a gate (an extension hooking tool calls) that routes each call to
unasked. A pure-JS package with ~23 dependencies: installs as a package tree,
like the DeepSeek Harness. Prefer the RPC mode: it keeps the agent out of the
host's process and is the same surface Oh My Pi speaks (below).
**Added** (`drivers/pi/`, see [PI.md](PI.md)): over RPC, with the gate as an
extension the driver writes into every session.

**GitHub Copilot CLI** (`@github/copilot`, proprietary). Reaches everyone who
has Copilot through an employer or the free tier. Speaks ACP
Expand Down
6 changes: 4 additions & 2 deletions docs/BRIDGE.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# The bridge

The bridge runs coding agents (OpenCode, Claude Code, the DeepSeek
Harness and Qwen Code) on your laptop or VPS and serves them to the CodeDeck+ Android app
Harness, Qwen Code and Pi) on your laptop or VPS and serves them to the CodeDeck+ Android app
over end-to-end encrypted Nostr (NIP-44). No accounts and no central server: the phone and the
bridge pair by scanning a QR code.

Expand Down Expand Up @@ -124,6 +124,8 @@ asked for:
`CODEDECK_DEEPSEEK_PATH` names a CLI to use instead.
- **Qwen Code**: a package tree too (`@qwen-code/qwen-code`);
`CODEDECK_QWEN_PATH` names a CLI to use instead.
- **Pi**: a package tree too (`@earendil-works/pi-coding-agent`);
`CODEDECK_PI_PATH` names a CLI to use instead.

Every download comes from the npm registry and is checked against the sha512
in this build's `pnpm-lock.yaml`; a mismatch is refused. Binaries live in
Expand All @@ -140,7 +142,7 @@ for it.
- Ahead of time: `codedeck-bridge agents install <agent>…` installs from the
terminal, into the same cache, before any phone asks.
- Offline machines: install `claude` (or `opencode`) yourself and it is used
as is, point `CODEDECK_DEEPSEEK_PATH` (or `CODEDECK_QWEN_PATH`) at one you
as is, point `CODEDECK_DEEPSEEK_PATH` (or `CODEDECK_QWEN_PATH`, `CODEDECK_PI_PATH`) at one you
installed, or copy an
`agents/` directory from another machine.
- A mirror: `CODEDECK_NPM_REGISTRY=https://…` (the sha512 still applies).
Expand Down
140 changes: 140 additions & 0 deletions docs/PI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Pi backend

[Pi](https://github.com/earendil-works/pi) runs over its RPC mode
(`pi --mode rpc`: JSON lines on stdio), one Pi process per session. The
driver is `packages/agent-host/src/drivers/pi/`.

## Getting it running

Nothing to install by hand: `@earendil-works/pi-coding-agent` is installed on
demand at the version and sha512 `pnpm-lock.yaml` pins, into `<home>/agents/`
— Install on the phone, or `codedeck-bridge agents install pi`. It is a
pure-JS package tree, like the DeepSeek Harness's. `CODEDECK_PI_PATH` names a
CLI of your own to use instead (its `cli.js`, run with the bridge's Node, or
an executable).

A session needs a model Pi can reach, any of:

- **An account** connected on the phone (the agent's page → Accounts): an
API key for any of Pi's providers, or a sign-in to a subscription where
Pi has one (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, xAI and
others). Pi's own code stores it, in its home (below), exactly where its
`/login` would. The model picker then lists that provider's models.
- **A provider profile** added on the phone (the agent's page → AI
providers): any OpenAI-compatible endpoint. A session bound to one runs on
it, and its models are the ones the picker offers.
- **The bridge's environment**: the keys Pi reads itself, such as
`ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY`. Accounts shows them as the
machine's, which only the machine can change.

## Accounts

The list is Pi's own: every provider the installed Pi knows, with a key
form where Pi takes a key and a sign-in where it has one. A key is checked
by Pi only when a session uses it.

A sign-in gives a page to open on any device. Some providers then show a
code to enter there and finish on their own; the others send the browser
back to an address on the bridge's machine, which a phone cannot open: paste
the address it fails to load, and Pi finishes the sign-in with it. A
provider whose login asks something more than a key or a sign-in (a
resource name, a region) is refused with Pi's question — run Pi's own
`/login` on the machine for it.

## Its own home

Pi's settings, credentials, models and conversations live in the directory
the driver points `PI_CODING_AGENT_DIR` at: `CODEDECK_PI_HOME`, else a `pi`
directory beside the agent cache. Pi in a terminal shares all of it when
pointed there (`PI_CODING_AGENT_DIR=<that directory>`): accounts, MCP
servers and packages added either way are there for both. Conversations are files under its `sessions/`, which is what a session
resumes from after a restart and what deleting a conversation removes.

A profile's token never touches a file: the driver hands the session's
process the profile in one environment variable and the token in another,
which the registration names (`$CODEDECK_PI_PROVIDER_TOKEN`), so Pi reads
the token from its own environment.

Pi runs with `--offline`, version checks and telemetry off: it makes no
network request of its own beyond the model's. Its model catalog is therefore
the one its release shipped with, plus your own `models.json`.

## Permissions

Pi has no permission system of its own: it runs every tool call it decides
on. CodeDeck installs an extension into every session —
`<home>/codedeck/codedeck-pi.js`, rewritten when the bridge's version of it
changes and loaded with `-e` — that holds each tool call until the phone
answers:

- **Ask** (the default): a card for every tool call, except Pi's read-only
tools (`read`, `grep`, `find`, `ls`), which run without one. The card
offers Allow, Allow `<tool>` for this session, and Deny; a denied call
never runs, and Pi tells the model it was denied. A tool that another
extension or an MCP server adds asks like any other.
- **Auto edit**: Pi's own file tools (`edit`, `write`) also run without a
card; a command, and any tool an extension or an MCP server adds, still
asks.
- **YOLO**: every tool call runs without a card.

What "for this session" allows is kept by the session only: Pi saves no
rules, so the next session asks again.

## Reasoning and messages

Reasoning is Pi's thinking level: Off, Minimal, Low, Medium (Pi's default),
High, Extra high, Max. A model without one of them runs at the nearest it
has, as in Pi's own terminal UI.

A message sent while a turn runs is steered into that turn: Pi hands it to
the model after the tool calls in flight, before its next request. Stop
aborts the turn and answers any card still open as cancelled.

When a request fails and Pi retries it, the session shows one line per
retry instead of an error; only an error Pi gives up on, or one it does not
retry, is shown as an error.

Dialogs that your own Pi extensions open (`select`, `confirm`, `input`,
`editor`) reach the phone as question cards; their notifications show as a
status line in the session.

## MCP servers

The MCP screen manages the `mcpServers` of `mcp.json` in Pi's home, the file
`pi mcp add` and `/mcp` edit. Stdio and streamable HTTP servers only: Pi
rejects the legacy SSE transport, and server names other than letters,
digits, `_` and `-`. Switching one off keeps it with Pi's own
`enabled: false`. A Pi process connects its servers as its session starts:
a change applies to the sessions started after it, and a session's MCP
panel shows a server changed since as not loaded yet. Env and header values
are kept in the file, which is written readable by its owner only on Linux
and macOS.

## Packages

The Plugins screen manages Pi's packages, through Pi's own `pi install`,
`pi update` and `pi remove`. A package bundles extensions, skills, prompt
templates and themes from npm (`npm:<package>`), git (`git:github.com/…` or
a URL) or a path, and is how Pi gains tools it does not ship — subagents,
LSP diagnostics and the like come from packages rather than from CodeDeck.
A package runs code with the bridge's permissions: install only ones you
trust. An npm package needs `npm` on the machine (the container image has
it, a release archive does not); `CODEDECK_NPM_REGISTRY` is passed on to it.
Packages cannot be switched off, only removed; sessions started after a
change load it.

## What this does not have

- **No question or plan tool**: Pi has neither, so the session shows no
question forms or plan cards of its own.
- **No subscription usage** to ask for (the context meter still works), no
background tasks and no saved permission rules.
- **Accounts need Pi's package**: with `CODEDECK_PI_PATH` naming an
executable rather than a `cli.js`, they cannot be listed or changed.

## Offline and container notes

Like the DeepSeek Harness it is a package tree in the `agents` volume. A host
without npm registry access installs it from a copied `agents/` directory,
points `CODEDECK_NPM_REGISTRY` at a mirror, or points `CODEDECK_PI_PATH` at
its own.
8 changes: 5 additions & 3 deletions docs/PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1010,9 +1010,11 @@ restart.
environment, and its runtime (what the machine already has, and how to
install the pinned one). Add it to the list in `src/host/modules.ts`; it
is enabled through `CODEDECK_AGENT_HOST_DRIVERS`.
The host ships four: `drivers/opencode/`, `drivers/claude/`,
`drivers/deepseek/` and `drivers/qwen/` (the last two over the shared
`acp/` machinery, which is what an ACP agent's driver reuses).
The host ships five: `drivers/opencode/`, `drivers/claude/`,
`drivers/deepseek/`, `drivers/qwen/` (those two over the shared `acp/`
machinery, which is what an ACP agent's driver reuses) and `drivers/pi/`
(Pi's own RPC mode, with an extension the driver writes for the
permission gate).
4. Test it beside the driver, in `src/drivers/<agent>/__tests__/`, like
`drivers/claude/__tests__/claudeDriver.test.ts` and
`drivers/opencode/__tests__/opencodeDriver.test.ts` do, with the
Expand Down
1 change: 1 addition & 0 deletions packages/agent-host/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
"devDependencies": {
"@agentclientprotocol/sdk": "^2.5.0",
"@deepseek-ai/dsh": "0.2.2-rc.1",
"@earendil-works/pi-coding-agent": "1.5.2",
"@opencode/cli": "2.2.7",
"@qwen-code/qwen-code": "0.27.1",
"@types/js-yaml": "^4.0.9",
Expand Down
Loading
Loading