{"id":51480314,"url":"https://github.com/paradise-runner/io","last_synced_at":"2026-07-07T01:01:10.610Z","repository":{"id":362136060,"uuid":"1256476584","full_name":"paradise-runner/io","owner":"paradise-runner","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-02T19:50:49.000Z","size":833,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T21:27:49.007Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/paradise-runner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-06-01T20:16:53.000Z","updated_at":"2026-06-02T19:50:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paradise-runner/io","commit_stats":null,"previous_names":["paradise-runner/io"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/paradise-runner/io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradise-runner%2Fio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradise-runner%2Fio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradise-runner%2Fio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradise-runner%2Fio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paradise-runner","download_url":"https://codeload.github.com/paradise-runner/io/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradise-runner%2Fio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35210429,"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-07-06T02:00:07.184Z","response_time":106,"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-07-07T01:01:09.879Z","updated_at":"2026-07-07T01:01:10.603Z","avatar_url":"https://github.com/paradise-runner.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# io\n\n`io` is a personal AI assistant TUI written in Go with Bubble Tea. It gives a\npersistent assistant persona a dedicated terminal interface, stores its state\nunder `~/.io`, and drives an installed agent CLI instead of calling a model API\ndirectly.\n\nThe current implementation supports Claude Code and Codex CLI harnesses, first\nrun persona setup, resumable sessions, local display history, model/effort\nsettings, context usage readouts, worker orchestration, automatic memory\nconsolidation, and a read-only memory view.\n\n![io TUI example](io-example.png)\n\n## Status\n\nThis repository contains the chat MVP, refreshed TUI, Phase 2 worker\norchestration/MCP plumbing, and Phase 3 compaction/dreamer behavior. Claude is\nrun as a live streaming persona and receives io's temporary MCP worker tools.\nCodex is run as resumable `codex exec --json` turns; Codex MCP wiring remains\ndisabled until verified.\n\n## Requirements\n\n- One or both supported agent CLIs installed and authenticated:\n  - `claude` for the Claude harness\n  - `codex` for the Codex harness\n- Go matching `go.mod` (`go 1.25.2`) when building from source\n\n## Installation\n\nPublished releases are installable from the Homebrew tap:\n\n```sh\nbrew install paradise-runner/tap/io\n```\n\nRelease binaries are attached to GitHub releases:\n\n```sh\n# example for Apple Silicon macOS\ncurl -Lo io.zip https://github.com/paradise-runner/io/releases/latest/download/io-darwin-arm64.zip\nunzip io.zip\ninstall -m755 io-darwin-arm64 /usr/local/bin/io\n```\n\n## Run\n\nStart the installed TUI:\n\n```sh\nio\n```\n\nOr run from the repository root:\n\n```sh\ngo run ./cmd/io\n```\n\nOn first run, `io` asks which harness to use and which personality preset to\nwrite into `~/.io/SOUL.md`. After setup, it starts the selected harness and\nresumes the saved session on later launches.\n\nFor an offline UI-only demo that does not require Claude or Codex:\n\n```sh\ngo run ./cmd/iodemo\n```\n\nThe demo uses generic canned tasks and local-only state so the UI can be shown,\ntested, and screenshotted without exposing a real workspace or agent session.\n\n## CLI Options\n\n```sh\ngo run ./cmd/io --harness codex --model gpt-5.4 --effort medium\n```\n\n| Flag | Description |\n| --- | --- |\n| `-harness`, `-agent-harness` | Agent harness: `claude` or `codex`. |\n| `-model`, `-agent-model` | Model override for the selected harness. |\n| `-effort`, `-agent-effort` | Reasoning effort: `low`, `medium`, or `high`. |\n| `-claude-path` | Path to a specific `claude` binary. |\n| `-codex-path` | Path to a specific `codex` binary. |\n| `-version` | Print the build version and exit. |\n\nDefaults are defined in `internal/agentharness`: Claude is the default harness,\nClaude defaults to `sonnet`, Codex defaults to `gpt-5.4`, and reasoning effort\ndefaults to `medium`.\n\n## Controls\n\nMain chat:\n\n- `Enter`: send the current message\n- `Ctrl+C`: quit\n- `Up` / `Down`: recall sent messages when the input is single-line\n- `PageUp` / `PageDown` or `Ctrl+U` / `Ctrl+D`: scroll chat history\n- Mouse wheel: scroll chat history\n\nToolbar screens:\n\n- `Ctrl+S`: Settings\n- `Ctrl+N`: New chat\n- `Ctrl+O`: Context usage\n- `Ctrl+R`: Memory\n\nSettings:\n\n- `Up` / `Down` / `Tab`: move between fields\n- `Left` / `Right`: change the selected field\n- `Enter`: save\n- `Esc`: return to chat\n\nContext:\n\n- `c`: request compaction now\n- `Esc`, `Enter`, or `q`: return to chat\n\n## Persistence\n\n`io` stores its own state under `~/.io`:\n\n| Path | Purpose |\n| --- | --- |\n| `~/.io/SOUL.md` | Generated and editable assistant personality prompt. |\n| `~/.io/state.json` | Selected harness, models, effort, thresholds, session IDs, and dream bookkeeping. |\n| `~/.io/history.jsonl` | Display transcript used to restore the TUI chat history. |\n| `~/.io/memory/` | Harness-backed assistant memory directory. |\n\nClaude sessions are run as a persistent streaming process. Codex turns are run\nthrough `codex exec --json` and resume the stored thread ID when available.\nClaude sessions receive a temporary MCP config for io's worker tools. Workers\nrun as bounded one-shot harness prompts, report status in the TUI, and inject\ntheir result back into the active conversation when finished.\n\nWhen the harness reports context usage above the configured threshold, io asks\nlive harnesses to compact. After enough completed chats and while the app is\nidle, the dreamer summarizes durable facts into `~/.io/memory/MEMORY.md`.\n\n## Development\n\nRun the normal test suite:\n\n```sh\ngo test ./...\n```\n\nRegenerate the checked-in screenshot used by the README and landing page:\n\n```sh\ngo run ./cmd/ioscreenshot io-example.png\n```\n\nThe screenshot generator drives `cmd/iodemo` in deterministic screenshot mode.\nIt requires macOS with Ghostty, tmux, clang, and `screencapture`. Ghostty must\nbe allowed in System Settings \u003e Privacy \u0026 Security \u003e Screen \u0026 System Audio\nRecording.\n\nInstall the `prek` pre-push hook that regenerates `io-example.png` before each\npush and stops the push when the committed PNG is stale:\n\n```sh\nprek install --hook-type pre-push\n```\n\nRun the real-Claude smoke test when `claude` is installed and authenticated:\n\n```sh\ngo test -tags=integration ./internal/persona\n```\n\nMost harness-facing tests use fake Claude and Codex binaries from\n`internal/persona/testdata/`, so the default suite is fast and offline.\n\n## Releases\n\nPush a `v*` tag to publish release binaries:\n\n```sh\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThe release workflow builds macOS and Linux binaries for `amd64` and `arm64`,\nuploads zipped assets plus `checksums.txt`, and updates\n`paradise-runner/homebrew-tap/io.rb`. The workflow needs a\n`HOMEBREW_TAP_TOKEN` repository secret with write access to the tap.\n\n## Project Layout\n\n| Path | Description |\n| --- | --- |\n| `cmd/io` | Main `io` application entrypoint and TUI controller adapter. |\n| `cmd/iodemo` | Offline canned-data TUI demo. |\n| `cmd/ioscreenshot` | Ghostty/tmux screenshot generator for `io-example.png`. |\n| `internal/agentharness` | Harness choices, model defaults, and normalization. |\n| `internal/claudeproc` | Parser and input encoder for Claude stream-json. |\n| `internal/codexproc` | Parser for Codex JSONL output. |\n| `internal/ioipc` | Local Unix-socket control protocol for worker operations. |\n| `internal/iomcp` | MCP stdio helper exposing io worker tools. |\n| `internal/persona` | Process controller for the selected harness. |\n| `internal/personastate` | `~/.io` paths and persisted state. |\n| `internal/soul` | First-run persona presets and `SOUL.md` rendering. |\n| `internal/tui` | Bubble Tea model, chat UI, controls, dialogs, and styling. |\n| `internal/workers` | Worker manager, lifecycle status, and harness runners. |\n| `docs/superpowers` | Design specs and implementation plans. |\n| `index.html` | Static visual prototype/mockup. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadise-runner%2Fio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparadise-runner%2Fio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadise-runner%2Fio/lists"}