Install and start the TUI
Install from the latest release with install.sh (or install.ps1 on Windows), then run `celagent` to open a Pi Coding Agent session with a unique persistence ID.
celagent · Pi TUI · BOS session authority
Pi TUI with sessions on object storage
A full Pi Coding Agent TUI with session authority on BOS. CAS writes keep history recoverable across machines; a task ledger covers distributed work.
$ celagent
COMMANDS
-
celagent -
celagent list -
celagent <id> # restore from BOS -
celagent task ledger
persistence Authority: BOS · Cache: worker SQLite · Restore: read BOS first · RPO≈0
Pi TUI · Celld/BOSCAS If-Match · cross-machine restore
Pi TUI + BOS persistence
Session authority on object storage
celagent runs a full Pi Coding Agent TUI. Each turn dual-writes a local worker cache and BOS with CAS; restore reads BOS first so sessions survive machine changes.
Persistence model
BOS is authority; the worker is a cache
Each turn dual-writes a local worker SQLite cache and BOS with CAS optimistic locking. Restore reads BOS first; the worker is only a miss fallback (RPO≈0).
- 01
Pi TUI turn
The pi-coding-agent engine handles interaction, tools, and models. A turn_end hook persists without blocking the chat.
- 02
Worker cache
Local SQLite holds a fast cache with a short write budget. Lost cache can be rebuilt from BOS.
- 03
BOS CAS write
Direct BOS writes use If-Match optimistic locking, idempotent dedupe, and an async queue. sessions/<id>.json keeps full turns.
- 04
Cross-machine restore
`celagent <id>` loads history from BOS. `list`, `doctor`, and `cas-probe` check recoverability and conditional-write readiness.
How a session runs
How a session runs
Each turn writes to BOS
On turn end, the worker caches locally and BOS is written with CAS optimistic locking. BOS is the session authority (RPO≈0); the worker is a miss fallback.
Restore on another machine
`celagent <id>` loads full history from BOS first. `celagent list` shows recoverable sessions; export and remove are available when you need them.
Submit distributed tasks
`celagent task submit/status/ledger` drives a Celld state machine with checkpoint resume and a per-cell idempotent ledger.
What it covers
Sessions and tasks that need durable object-storage state
cross-machine session restoreBOS-backed conversation historyCAS conflict detectiondistributed task submit / statusidempotent task ledgerdoctor and cas-probe checks
Use celagent when a Pi TUI session must survive machine changes, local cache loss, or multi-step Celld work.
Questions & how-to
How do I install it?
On Unix: `curl -fsSL https://github.com/hxddh/celagent/releases/latest/download/install.sh | sh`. On Windows: run install.ps1 from the same release (CLI only; upstream Celld has no Windows package).
Where does session authority live?
On BOS. Each turn dual-writes a worker cache and BOS with CAS. Restore reads BOS first; the worker is only a miss fallback.
Does it fork Pi?
No. It reuses the pi-coding-agent engine with the full tool set (bash, read, write, grep, find, edit, ls) and multi-model switching.
What license does it use?
MIT.