chore: prepare v0.5.0 release

changelog.md

@@ -1,15 +1,17 @@
 # changelog
 
-## v0.5.0 (unreleased)
+## v0.5.0 (2026-01-02)
 
 ### changes
 
-- add a pi runner via the `pi` CLI with jsonl streaming and resume support
+- add an opencode runner via the `opencode` CLI with json event parsing and resume support
-- document the pi runner, event mapping, and jsonl stream capture tips
+- add a pi agent runner via the `pi` CLI with jsonl streaming and resume support
+- document the opencode and pi runners, event mappings, and stream capture tips
 
 ### fixes
 
-- TBD
+- fix path relativization so progress output does not strip sibling directories
+- reduce noisy debug logging from markdown_it/httpcore
 
 ## v0.4.0 (2026-01-02)
 

docs/runner/claude/claude-runner.md

@@ -1,4 +1,4 @@
-Below is a concrete implementation spec for adding **Anthropic Claude Code (“claude” CLI / Agent SDK runtime)** as a first-class engine in Takopi (v0.2.0).
+Below is a concrete implementation spec for the **Anthropic Claude Code (“claude” CLI / Agent SDK runtime)** runner shipped in Takopi (v0.3.0).
 
 ---
 
@@ -6,7 +6,7 @@ Below is a concrete implementation spec for adding **Anthropic Claude Code (“c
 
 ### Goal
 
-Add a new engine backend **`claude`** so Takopi can:
+Provide the **`claude`** engine backend so Takopi can:
 
 * Run Claude Code non-interactively via the **Agent SDK CLI** (`claude -p`). ([Claude Code][1])
 * Stream progress in Telegram by parsing **`--output-format stream-json --verbose`** (newline-delimited JSON). Note: `--output-format` only works with `-p/--print`. ([Claude Code][1])
@@ -24,11 +24,11 @@ Add a new engine backend **`claude`** so Takopi can:
 
 ### Engine selection
 
-* Existing: `takopi codex`
+* Default: `takopi` (auto-router uses `default_engine` from config)
-* New: `takopi claude`
+* Override: `takopi claude`
 
-Takopi requires an explicit engine subcommand; `takopi` alone prints the engine
+Takopi runs in auto-router mode by default; `takopi claude` or `/claude` selects
-selection panel and exits.
+Claude for new threads.
 
 ### Resume UX (canonical line)
 
@@ -74,11 +74,11 @@ Recommended v1 schema:
 ```toml
 # .takopi/takopi.toml
 
-engine = "claude"
+default_engine = "claude"
 
 [claude]
 model = "claude-sonnet-4-5-20250929" # optional (Claude Code supports model override in settings too)
-allowed_tools = "Bash,Read,Edit"     # optional but strongly recommended for automation
+allowed_tools = ["Bash", "Read", "Edit"] # optional but strongly recommended for automation
 dangerously_skip_permissions = false # optional (high risk; prefer sandbox use only)
 use_api_billing = false             # optional (keep ANTHROPIC_API_KEY for API billing)
 ```
@@ -365,13 +365,13 @@ Mirror the existing `CodexRunner` tests patterns.
 
 ---
 
-## Implementation checklist
+## Implementation checklist (v0.3.0)
 
-* [ ] Export `BACKEND = EngineBackend(...)` from `src/takopi/runners/claude.py`.
+* [x] Export `BACKEND = EngineBackend(...)` from `src/takopi/runners/claude.py`.
-* [ ] Add `src/takopi/runners/claude.py` implementing the `Runner` protocol.
+* [x] Add `src/takopi/runners/claude.py` implementing the `Runner` protocol.
-* [ ] Add tests + stub executable fixtures.
+* [x] Add tests + stub executable fixtures.
-* [ ] Update README and developing docs.
+* [x] Update README and developing docs.
-* [ ] Run full test suite.
+* [ ] Run full test suite before release.
 
 ---
 

docs/runner/claude/claude-takopi-events.md

@@ -1,8 +1,8 @@
 # Claude Code -> Takopi event mapping (spec)
 
-This document specifies how to add a Claude Code runner to Takopi by translating
+This document specifies how the Claude Code runner (implemented in Takopi v0.3.0)
-Claude CLI `--output-format stream-json` JSONL events into Takopi events. It is
+translates Claude CLI `--output-format stream-json` JSONL events into Takopi events.
-based on the reverse-engineered schema in `humanlayer/claudecode-go`:
+It is based on the reverse-engineered schema in `humanlayer/claudecode-go`:
 
 - `claudecode-go/types.go` (StreamEvent, Message, Content, Result)
 - `claudecode-go/client.go` (CLI flags, stream parsing)
@@ -196,18 +196,18 @@ without transformation. Optionally include `modelUsage` inside `usage` or
 
 ---
 
-## 7. Implementation checklist (handoff)
+## 7. Implementation checklist (v0.3.0)
 
-Add a Claude runner without changing the Takopi domain model:
+Claude runner implementation summary (no Takopi domain model changes):
 
-1. Create `takopi/runners/claude.py` implementing `Runner` and (custom)
+1. [x] Create `takopi/runners/claude.py` implementing `Runner` and (custom)
    resume parsing.
-2. Define `BACKEND` in `takopi/runners/claude.py`:
+2. [x] Define `BACKEND` in `takopi/runners/claude.py`:
    - `install_cmd`: install command for the `claude` binary
    - `build_runner`: read `[claude]` config + construct runner
-3. Add new docs (this file + `claude-stream-json-cheatsheet.md`).
+3. [x] Add new docs (this file + `claude-stream-json-cheatsheet.md`).
-4. Add fixtures in `tests/fixtures/` (see below).
+4. [x] Add fixtures in `tests/fixtures/` (see below).
-5. Add unit tests mirroring `tests/test_codex_*` but for Claude translation
+5. [x] Add unit tests mirroring `tests/test_codex_*` but for Claude translation
    and resume parsing (recommended, not required for initial handoff).
 
 ---

docs/runner/opencode/opencode-runner.md

@@ -1,6 +1,7 @@
 # OpenCode Runner
 
 This runner integrates with the [OpenCode CLI](https://github.com/sst/opencode).
+Shipped in Takopi v0.5.0.
 
 ## Installation
 

docs/runner/opencode/opencode-takopi-events.md

@@ -1,6 +1,7 @@
 # OpenCode to Takopi Event Mapping
 
 This document describes how OpenCode JSON events are translated to Takopi's normalized event model.
+The OpenCode runner shipped in Takopi v0.5.0.
 
 ## Event Translation
 

docs/runner/pi/pi-runner.md

@@ -1,4 +1,4 @@
-Below is a concrete implementation spec for adding **Pi (pi-coding-agent CLI)** as a first-class engine in Takopi (v0.4.0).
+Below is a concrete implementation spec for the **Pi (pi-coding-agent CLI)** runner shipped in Takopi (v0.5.0).
 
 ---
 
@@ -6,7 +6,7 @@ Below is a concrete implementation spec for adding **Pi (pi-coding-agent CLI)**
 
 ### Goal
 
-Add a new engine backend **`pi`** so Takopi can:
+Provide the **`pi`** engine backend so Takopi can:
 
 * Run Pi non-interactively via the **pi CLI** (`pi --print`).
 * Stream progress by parsing **`--mode json`** (newline-delimited JSON). Each line is a JSON object.
@@ -23,8 +23,8 @@ Add a new engine backend **`pi`** so Takopi can:
 
 ### Engine selection
 
-* Existing: `takopi codex`
+* Default: `takopi` (auto-router uses `default_engine` from config)
-* New: `takopi pi`
+* Override: `takopi pi`
 
 ### Resume UX (canonical line)
 

docs/runner/pi/pi-takopi-events.md

@@ -1,6 +1,6 @@
 # Pi -> Takopi event mapping (spec)
 
-This document specifies how to add a Pi runner to Takopi by translating
+This document specifies how the Pi runner shipped in Takopi v0.5.0 translates
 Pi CLI `--mode json` JSONL events into Takopi events. The Pi JSONL stream is
 `AgentSessionEvent` from `@mariozechner/pi-agent-core`.
 

docs/specification.md

@@ -1,10 +1,10 @@
-# Takopi Specification v0.4.0 [2026-01-01]
+# Takopi Specification v0.5.0 [2026-01-02]
 
 This document is **normative**. The words **MUST**, **SHOULD**, and **MAY** express requirements.
 
 ## 1. Scope
 
-Takopi v0.4.0 specifies:
+Takopi v0.5.0 specifies:
 
 - A **Telegram** bot bridge that runs an agent **Runner** and posts:
   - a throttled, edited **progress message**
@@ -15,7 +15,7 @@ Takopi v0.4.0 specifies:
 - **Automatic runner selection** among multiple engines based on ResumeLine (with a configurable default for new threads)
 - A Takopi-owned **normalized event model** produced by runners and consumed by renderers/bridge
 
-Out of scope for v0.4.0:
+Out of scope for v0.5.0:
 
 - Non-Telegram clients (Slack/Discord/etc.)
 - Token-by-token streaming of the assistant’s final answer
@@ -405,6 +405,10 @@ Test tooling SHOULD include event factories, deterministic/fake time, and a scri
 
 ## 10. Changelog
 
+### v0.5.0 (2026-01-02)
+
+- No normative changes; align spec version with the v0.5.0 release.
+
 ### v0.4.0 (2026-01-01)
 
 - Add auto-router engine selection by polling all runners to decode resume lines; add configurable default engine for new threads (subcommand overrides default).

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "takopi"
 authors = [{name = "banteg"}]
-version = "0.5.0.dev0"
+version = "0.5.0"
 description = "Telegram bridge for Codex, Claude Code, and other agent CLIs."
 readme = "readme.md"
 license = { file = "LICENSE" }

readme.md

@@ -2,7 +2,7 @@
 
 🐙 *he just wants to help-pi*
 
-telegram bridge for codex, claude code, pi, and [other agents](docs/adding-a-runner.md). runs the agent cli, streams progress, and supports resumable sessions.
+telegram bridge for codex, claude code, opencode, pi, and [other agents](docs/adding-a-runner.md). runs the agent cli, streams progress, and supports resumable sessions.
 
 ## features
 
@@ -22,6 +22,7 @@ parallel runs across threads, per thread queue support.
 - at least one engine installed:
   - `codex` on PATH (`npm install -g @openai/codex` or `brew install codex`)
   - `claude` on PATH (`npm install -g @anthropic-ai/claude-code`)
+  - `opencode` on PATH (`npm install -g opencode-ai@latest`)
   - `pi` on PATH (`npm install -g @mariozechner/pi-coding-agent`)
 
 ## install
@@ -71,6 +72,7 @@ cd ~/dev/your-repo
 takopi
 # or override the default engine for new threads:
 takopi claude
+takopi opencode
 takopi pi
 ```
 
@@ -78,7 +80,7 @@ resume lines always route to the matching engine; subcommands only override the
 
 send a message to the bot.
 
-start a new thread with a specific engine by prefixing your message with `/codex` or `/claude`.
+start a new thread with a specific engine by prefixing your message with `/codex`, `/claude`, `/opencode`, or `/pi`.
 
 to continue a thread, reply to a bot message containing a resume line.
 you can also copy it to resume an interactive session in your terminal.

src/takopi/__init__.py

@@ -1 +1 @@
-__version__ = "0.5.0.dev0"
+__version__ = "0.5.0"

src/takopi/cli.py

@@ -177,9 +177,8 @@ def _parse_bridge_config(
     engine_list = ", ".join(router.engine_ids)
     startup_msg = (
         f"\N{OCTOPUS} **takopi is ready**\n\n"
-        f"mode: `auto-router`  \n"
         f"default: `{router.default_engine}`  \n"
-        f"engines: `{engine_list}`  \n"
+        f"agents: `{engine_list}`  \n"
         f"working in: `{startup_pwd}`"
     )
 

uv.lock

@@ -354,7 +354,7 @@ wheels = [
 
 [[package]]
 name = "takopi"
-version = "0.5.0.dev0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },