{"id":50656179,"url":"https://github.com/Snailflyer/faryo","last_synced_at":"2026-06-24T20:00:40.952Z","repository":{"id":359012976,"uuid":"1240453130","full_name":"Snailflyer/faryo","owner":"Snailflyer","description":"Lightweight project/mobile workbench for same tmux-backed AI coding sessions; not remote desktop or a second AI chat.","archived":false,"fork":false,"pushed_at":"2026-06-10T10:23:11.000Z","size":1805,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T11:21:34.094Z","etag":null,"topics":["agentic-coding","ai-agents","ai-coding","android","claude-code","codex-cli","coding-agents","developer-tools","handoff","linux","mobile","mobile-workbench","project-management","pwa","remote-control","same-session","self-hosted","terminal","terminal-ai","tmux"],"latest_commit_sha":null,"homepage":"https://github.com/Snailflyer/faryo/releases/tag/v1.0.9","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Snailflyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-16T06:33:04.000Z","updated_at":"2026-06-10T10:23:12.000Z","dependencies_parsed_at":"2026-05-20T05:00:06.589Z","dependency_job_id":null,"html_url":"https://github.com/Snailflyer/faryo","commit_stats":null,"previous_names":["snailflyer/faryo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Snailflyer/faryo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snailflyer%2Ffaryo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snailflyer%2Ffaryo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snailflyer%2Ffaryo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snailflyer%2Ffaryo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Snailflyer","download_url":"https://codeload.github.com/Snailflyer/faryo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snailflyer%2Ffaryo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34747387,"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-06-24T02:00:07.484Z","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":["agentic-coding","ai-agents","ai-coding","android","claude-code","codex-cli","coding-agents","developer-tools","handoff","linux","mobile","mobile-workbench","project-management","pwa","remote-control","same-session","self-hosted","terminal","terminal-ai","tmux"],"created_at":"2026-06-08T00:00:30.254Z","updated_at":"2026-06-24T20:00:40.946Z","avatar_url":"https://github.com/Snailflyer.png","language":"Python","funding_links":[],"categories":["🛠️ Developer Productivity \u0026 Workflow"],"sub_categories":[],"readme":"# Faryo\n\nFaryo is a lightweight project and mobile workbench for the same live\n`tmux`-backed Codex CLI, Claude Code, or shell session.\n\nUse it to open a project deck, check what an agent is doing, send one\ninstruction, approve or interrupt work, attach context, and return to the same\ndesktop terminal session. It is not remote desktop, a hosted IDE, a browser\nterminal, or a second AI chat history.\n\nCanonical repository: https://github.com/Snailflyer/faryo\n\n## Visual Proof\n\n\u003cp\u003e\n  \u003cimg src=\"docs/assets/screenshots/faryo-projects-workbench-redacted.png\" alt=\"Faryo Projects workbench showing project cards, Run, Import, Saved, and Decision Action Watch counts\" width=\"250\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/faryo-project-control-promo.png\" alt=\"Faryo project control surface showing project cards routed to the same tmux session\" width=\"250\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/faryo-project-run-session-main.gif\" alt=\"Faryo project queue Run action opening a live tmux-backed owner session\" width=\"250\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/faryo-same-session-handoff-walkthrough.gif\" alt=\"Faryo same-session handoff walkthrough showing browser workbench and terminal session continuity\" width=\"250\"\u003e\n\u003c/p\u003e\n\nThe project workbench keeps project state, owner decisions, actions, watch\nitems, and the live session route in one phone-sized surface. The project-run\nwalkthrough shows a queued project action opening a live `tmux`-backed owner\nsession. The same-session handoff walkthrough demonstrates the other half of the\ncontract: browser actions return to the same live `tmux` session instead of\ncreating a detached mobile chat or stale terminal copy.\n\n## Current Release\n\n- Linux endpoint package: `faryo_1.1.0_all.deb`\n- macOS endpoint package: `faryo_1.1.0_macos.tar.gz`\n- Release page: https://github.com/Snailflyer/faryo/releases/tag/v1.1.0\n- Launch guide: [docs/launch/faryo-1.0.0.md](docs/launch/faryo-1.0.0.md)\n- Troubleshooting:\n  [docs/launch/faryo-1.0.0.md#troubleshooting--deployment-verification](docs/launch/faryo-1.0.0.md#troubleshooting--deployment-verification)\n\n## Use It For\n\n- check a long-running terminal AI task from a phone\n- send a short follow-up without opening a raw terminal\n- approve, interrupt, attach files, or hand off notes\n- keep phone and desktop on the same `tmux` session history\n- keep project decisions, action items, and watch items close to the live agent\n  session that will execute them\n\nBest-supported path:\n\n```text\nLinux endpoint\n  + tmux\n  + Codex CLI\n  + Chrome / Android Chrome PWA\n```\n\nmacOS Owner packaging, iOS Safari, Claude Code session discovery, and generic\nshell TUIs are supported but less polished.\n\n## Quickstart\n\n```bash\ncurl -LO https://github.com/Snailflyer/faryo/releases/download/v1.1.0/faryo_1.1.0_all.deb\nsudo dpkg -i faryo_1.1.0_all.deb\nsystemctl --user daemon-reload\nsystemctl --user enable --now faryo-owner-keepalive.timer\nmkdir -p ~/.faryo/owner/config\ncp /opt/faryo/apps/owner/config/faryo.env.example ~/.faryo/owner/config/faryo.env\n$EDITOR ~/.faryo/owner/config/faryo.env\ncurl --noproxy '*' http://127.0.0.1:8765/health\n```\n\n- [Troubleshooting \u0026 Deployment Verification](docs/launch/faryo-1.0.0.md#troubleshooting--deployment-verification)\n\nOwner should bind to `127.0.0.1`. Public access should go through Gateway, which\ninjects Owner tokens server-side so browsers do not receive raw Owner tokens.\n\n## How It Works\n\nFaryo has two small components:\n\n```text\nphone / desktop browser\n  -\u003e Faryo Gateway\n  -\u003e Owner endpoint\n  -\u003e tmux session\n  -\u003e Codex, Claude, or shell TUI\n```\n\n`apps/gateway` is the public workbench. It owns login, route authorization,\nendpoint health, session selection, handoff packages, and proxying to Owner\nendpoints. It also renders the project deck, owner decisions, action queues,\nwatch items, and run handoffs that route approved work back to the selected\nlive session. Owner tokens are injected server-side and are not exposed to the\nbrowser.\n\n`apps/owner` is the local execution surface. It binds to loopback, controls a\ntarget `tmux` pane, captures terminal output, sends text, uploads attachments to\na configured inbox, and discovers resumable Codex/Claude history.\n\nThe browser UI stays thin. It renders the workbench, sends commands, uploads\nattachments, and switches sessions; it does not replace the terminal runtime.\n\nThe endpoint package intentionally includes only Owner. Gateway is source\ndeployed because it is the public routing and policy layer.\n\n## Endpoint Fit\n\nFaryo is built around a lightweight browser workbench, but endpoints and\nbrowsers do not behave identically.\n\nThe most refined path today is:\n\n```text\nLinux endpoint\n  + tmux\n  + Codex CLI\n  + Chrome / Android Chrome PWA\n```\n\nThat path has received the most tuning for mobile viewport behavior, PWA use,\ncompact output, command input, attachment handling, session switching, and\nCodex history convergence.\n\nSupported but less heavily polished paths:\n\n- macOS Owner packaging through the launchd installer.\n- iOS Safari as a browser surface.\n- Claude Code session discovery and compact rendering.\n- Generic shell TUIs controlled through tmux capture/send.\n\nThese paths are usable, but they may need additional refinement around browser\nviewport behavior, backgrounding, paste/input edge cases, compact rendering, and\nagent-specific session history mapping.\n\n## Agent Convergence\n\nFaryo treats \"session convergence\" as the process of making four things line up:\n\n```text\nactive tmux session\n  + visible terminal process\n  + agent history record\n  + workbench session card\n```\n\nDifferent agents expose different state, so Faryo uses different convergence\nrules.\n\nCodex is the most mature integration:\n\n- reads the Codex local session database\n- filters internal and subagent branches from normal history\n- maps the active tmux process back to the current Codex thread\n- resumes sessions through `codex resume`\n- applies Codex-specific compact output rules\n\nClaude is supported with a different path:\n\n- reads Claude project JSONL history\n- tracks managed Claude tmux sessions with Faryo tmux metadata\n- resumes sessions through Claude session IDs\n- applies Claude-specific compact output rules\n\nClaude convergence is intentionally separate from Codex convergence. It is not\nas heavily tuned yet, especially across macOS, iOS Safari, and less common\nClaude output states.\n\nGeneric shell sessions are controlled through tmux only. They can be captured,\nviewed, and sent input, but they do not have Codex/Claude-style semantic history\nconvergence.\n\n## UI Interaction Model\n\nFaryo's UI is a workbench, not a document editor or chat clone. The main screen\nis optimized for repeated mobile checks and short control actions. Screenshots\nnear the top are redacted examples.\n\nCore interactions:\n\n- Workbench first: Gateway opens to route status, project cards, active\n  sessions, recent history, and pending handoff packages.\n- Project deck: project cards keep decisions, action items, watch items,\n  stage goals, and owner review close to the session that can execute them.\n- Run queue: approved project actions can be dispatched back to the live Faryo\n  session instead of becoming a disconnected task list.\n- Session cards: each card represents a resumable agent session or active tmux\n  session. Opening a card routes the browser to that endpoint and session.\n- Compact output: the default mobile view reduces noisy terminal output into\n  readable work blocks while keeping the session grounded in terminal history.\n- Raw output: full terminal capture is available when exact terminal evidence is\n  needed.\n- Latest control: when the user scrolls up, Faryo does not force-jump the view;\n  new output waits until the user taps the latest control.\n- Composer: the bottom input sends text into the active tmux pane. It works well\n  with mobile keyboards and system dictation.\n- Attachments: images and files can be uploaded into the configured inbox and\n  referenced in the active session.\n- Handoff packages: prompts, notes, screenshots, and files can be picked up and\n  injected into a selected session.\n- Agent controls: interrupt, approve, page up/down, resume, and close actions\n  are exposed as direct controls instead of hidden terminal shortcuts.\n- Thin state: the browser remembers display preferences, but the work session\n  itself remains in tmux and the agent history store.\n\nThe UI intentionally avoids heavyweight panels and IDE-style layout. It should\nfeel fast enough to open, inspect, dictate a command, attach context, and leave.\n\n## Core Features\n\n- Project workbench with project cards, owner decisions, action items, watch\n  items, stage goals, and run queue handoff.\n- Mobile-first PWA workbench with compact and raw terminal views.\n- Shared session history across phone and desktop through the same `tmux`\n  session.\n- Codex and Claude session discovery, resume, interrupt, and approval controls.\n- Multi-endpoint routing for local machines and cloud endpoints.\n- Handoff packages for prompts, notes, images, and files.\n- Lightweight attachment handling with local inbox paths.\n- No browser automation, no remote desktop stack, and no database server in the\n  runtime path.\n\n## Runtime State\n\nSource code lives in this repository. Runtime configuration and secrets do not.\n\n```text\n~/.faryo/\n  gateway/\n    config/faryo.env\n    config/gateway-auth.json\n    state/\n    logs/\n  owner/\n    config/faryo.env\n    data/\n```\n\nExample configuration files live under:\n\n```text\napps/gateway/config/faryo.env.example\napps/owner/config/faryo.env.example\n```\n\n## Requirements\n\nOwner endpoint:\n\n- Python 3.11 or newer\n- `tmux`\n- `curl`\n- `zsh`\n- optional: `git`, `openssh-client`, Codex CLI, Claude Code\n\nGateway:\n\n- Python 3.11 or newer\n- `bcrypt`\n- a reverse proxy such as Caddy or nginx for public HTTPS\n\n## Packaging\n\nEndpoint releases are built from `apps/owner/RELEASE`.\n\n```bash\nscripts/package-client.sh check\nscripts/package-client.sh release\n```\n\nThe release target builds:\n\n```text\ndist/faryo_\u003cversion\u003e_all.deb\ndist/faryo_\u003cversion\u003e_macos.tar.gz\ndist/SHA256SUMS\n```\n\nInstall the Linux endpoint package on an Owner machine:\n\n```bash\nsudo dpkg -i dist/faryo_\u003cversion\u003e_all.deb\nsystemctl --user daemon-reload\nsystemctl --user enable --now faryo-owner-keepalive.timer\n```\n\nAfter configuration, the Owner health and status endpoints should answer on\nloopback. `releaseVersion` in `/api/status` is the endpoint version to use for\nupgrade acceptance.\n\n## Repository Layout\n\n```text\napps/gateway/       Public gateway, login, routing, and handoff workbench\napps/owner/         Local tmux-backed execution endpoint\npackages/shared/    Shared code and contracts as they are extracted\ndocs/               Product, launch, release, UI, and client sync notes\ndeploy/             Runtime unit templates\nscripts/            Packaging, endpoint install, and verification tools\n```\n\n## Security Model\n\nFaryo is designed for a trusted operator running their own endpoints.\n\n- Owner should bind only to `127.0.0.1`.\n- Public access should go through Gateway.\n- Tokens, password hashes, cookie secrets, and runtime env files are private\n  runtime state.\n- File preview and attachment APIs are token-protected and constrained by\n  supported file types.\n- Gateway bridge URL attachments reject private, loopback, link-local,\n  multicast, reserved, and unresolved hosts.\n\nSee `SECURITY.md` for the short disclosure and deployment guidance.\n\n## License\n\nFaryo is released under the MIT License. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnailflyer%2Ffaryo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSnailflyer%2Ffaryo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnailflyer%2Ffaryo/lists"}