{"id":49013389,"url":"https://github.com/jyao97/xylocopa","last_synced_at":"2026-05-10T20:03:10.722Z","repository":{"id":348798540,"uuid":"1165697163","full_name":"jyao97/xylocopa","owner":"jyao97","description":"Manage your AI worker bees easily — all in one, all at once. Could possibly be your handy workspace for the AI agent era 🐝","archived":false,"fork":false,"pushed_at":"2026-04-19T00:29:50.000Z","size":8836,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-19T00:32:26.280Z","etag":null,"topics":["agentic-coding","ai-agents","claude","claude-code","developer-tools","mobile-first","multi-agent","pwa","task-management","tmux","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jyao97.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-02-24T12:55:33.000Z","updated_at":"2026-04-19T00:26:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jyao97/xylocopa","commit_stats":null,"previous_names":["jyao97/agenthive","jyao97/xylocopa"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/jyao97/xylocopa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jyao97%2Fxylocopa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jyao97%2Fxylocopa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jyao97%2Fxylocopa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jyao97%2Fxylocopa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jyao97","download_url":"https://codeload.github.com/jyao97/xylocopa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jyao97%2Fxylocopa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32253252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T04:23:17.126Z","status":"ssl_error","status_checked_at":"2026-04-25T04:21:53.360Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","claude","claude-code","developer-tools","mobile-first","multi-agent","pwa","task-management","tmux","vibe-coding"],"created_at":"2026-04-19T00:18:52.956Z","updated_at":"2026-05-03T08:01:47.641Z","avatar_url":"https://github.com/jyao97.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xylocopa\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![React 19](https://img.shields.io/badge/react-19-61dafb.svg)](https://react.dev)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688.svg)](https://fastapi.tiangolo.com)\n\n\u003e [**The Loop**](#the-loop) · [**Getting Started**](#getting-started) · [**Features**](#features) · [**Architecture**](docs/ARCHITECTURE.md) · [**Contributing**](CONTRIBUTING.md) · [**新手入门（中文）**](docs/getting-started-zh.md)\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/hero.png\" alt=\"Xylocopa — Many projects. One attention.\" width=\"640\"\u003e\u003c/p\u003e\n\n_Named after [Xylocopa caerulea](https://en.wikipedia.org/wiki/Xylocopa_caerulea): the blue carpenter bee._\n\nXylocopa aims to help you navigate attention across many [Claude Code](https://docs.anthropic.com/en/docs/claude-code) projects. Inspired by [GTD](https://gettingthingsdone.com/what-is-gtd/) — except here, agents do the work, not you.\n\nIf you find Xylocopa useful, a star helps others find it :)\n\n| \u003cimg src=\"docs/pwa/inbox.png\" alt=\"Inbox\" width=\"220\"\u003e | \u003cimg src=\"docs/pwa/projects.png\" alt=\"Projects\" width=\"220\"\u003e | \u003cimg src=\"docs/pwa/agents.png\" alt=\"Agents\" width=\"220\"\u003e |\n|:---:|:---:|:---:|\n| Inbox | Projects | Agents |\n| \u003cimg src=\"docs/pwa/chat-insights.png\" alt=\"Chat with Progress Insights\" width=\"220\"\u003e | \u003cimg src=\"docs/pwa/git.png\" alt=\"Git\" width=\"220\"\u003e | \u003cimg src=\"docs/pwa/monitor.png\" alt=\"Monitor\" width=\"220\"\u003e |\n| Chat | Git | Monitor |\n\n## The Loop\n\nClassic [GTD](https://gettingthingsdone.com/what-is-gtd/) has one human do all five steps (capture, clarify, organize, reflect, engage). Xylocopa keeps the loop but rewires the executor: **you capture and decide, agents execute, the system remembers.**\n\n### 1. Capture\n\nGet ideas into the system, fast, from anywhere.\n\n- **Inbox**: a persistent queue across all your projects.\n- **Voice input**: speech-to-text for quick ideas on the go.\n- **Lightning input**: title, project, go.\n- **Draft persistence**: every keystroke cached locally, survives app close or network drop.\n\n### 2. Dispatch\n\nTurn tasks into agents and let them run.\n\n- **Task → Agent**: one click. Pick a model (Opus/Sonnet/Haiku), optionally enable **Auto mode** (`--dangerously-skip-permissions`; destructive commands still blocked by the [safety hook](#safety-guardrails)).\n- **Parallel execution**: run many agents at once, each in its own isolated git worktree.\n- **AI batch dispatch**: one click to triage and fire off a pile of inbox tasks.\n- **RAG-powered context**: new agents are seeded with relevant lessons from past sessions in the same project.\n- **Cross-session reference**: tell an agent \"check xy session `\u003cid\u003e`\" and it reads another agent's curated display file via a built-in [MCP server](orchestrator/mcp_server.py), ~54× fewer tokens than raw JSONL.\n\n### 3. Monitor\n\nWatch everything in real time, from desk or phone.\n\n- **Mobile-first PWA**: add to Home Screen on iOS/Android.\n- **Split screen**: 2/3/4 panes side by side, each navigating independently.\n- **Attention button**: draggable FAB with a cyan unread badge. Tap for the oldest unread (FIFO), long-press for split screen.\n- **Rich chat**: markdown, inline media, interactive cards for tool approvals and plan review.\n- **Compact chat header**: status dot next to the title, tinted Stop / Resume / OK pills on row 1; project / worktree icon-pill / Auto / Task / 4-char id pill collapsed into one tag row underneath. Hover or long-press the id pill for a `xylo id:` popover, double-click to copy; same interaction on the worktree pill.\n\n  ![Chat header](docs/getting-started/12-chat-header.png)\n- **Dual-directional CLI sync**: CLI sessions show up in the web app; web sessions are resumable from the CLI via `tmux attach -t xy-\u003cid\u003e` (legacy `ah-` still recognized).\n\n  ![CLI sync demo](docs/cli-sync.gif)\n- **Smart notifications**: Web Push, suppressed when you're already viewing the agent (WebSocket or tmux). Permission requests always cut through.\n- **Context usage pill**: per-agent context-window meter on the chat header — live percentage with a tap-to-expand breakdown (system / tools / MCP / messages / cache split, free vs. used). Inline suggestion when usage gets high. Counts come straight from the Claude Code session JSONL, not estimated.\n- **System monitoring**: disk, memory, GPU, token usage. Per-agent **lifetime cost** (cumulative spend across resumes, deduped by message id; Opus / Sonnet / Haiku priced separately, with 5m/1h cache split).\n- **E-ink display mode**: a Settings → Display toggle (and auto-detect for BOOX / Onyx / Kindle / Bigme / Hisense / Meebook / iReader user agents) that flattens glass effects, collapses colored badges to grayscale, and switches saturated bubbles to outlined style for readable contrast on e-paper screens.\n\n### 4. Review\n\nCheck results, give feedback, grow the knowledge.\n\n- **Mark done**: approve and close the task.\n- **Try → Summarize → Retry**: stop a miss, Xylocopa auto-summarizes what was tried, the next agent picks up from there.\n- **Git operations**: diffs, commit history, branch status per project. One-click cleanup and push.\n- **Curated project memory**: lessons accumulate in a per-project `PROGRESS.md` that you edit and review; relevant entries are retrieved (top-k) for future agents.\n\n### 5. Remember\n\nKnowledge compounds across sessions, projects, and time.\n\n- **Project memory**: per-project `PROGRESS.md`, fully UI-managed.\n- **Session archive**: every conversation persisted, searchable, starrable.\n- **Bookmark messages**: double-tap a chat bubble → **Bookmark** to save standout turns. Each bookmark stores your optional note plus an LLM-generated summary + emoji; a per-project **Bookmarks** section lists them, tap a row to jump back with a yellow focus-flash on the original turn.\n- **Resume anytime**: pick up any agent where it left off.\n- **Full-text search**: across tasks, messages, and sessions.\n- **Weekly progress stats**: see the trend, not just the backlog.\n- **Automatic backups**: DB + session history + project configs, on a configurable schedule.\n\n## Why Xylocopa?\n\n### Why not just use `claude`?\n\nVanilla `claude` is fine for one-off sessions. It frays once you run several in parallel, across multiple projects, over multiple days.\n\n- **Attention across agents**: one **Attention button** with a badge for unread/waiting agents. Tap for the oldest, long-press for split-screen. Per-project dashboards with weekly stats, LLM-generated recaps, and an in-project search bar.\n- **Capture on the go**: a PWA with voice input (Whisper), ⚡ quick-save to inbox, triage at the desk later. Every keystroke auto-drafts locally across 13+ input surfaces.\n- **Find and resume old work**: full-text search across every session, with star-to-pin. One-click resume brings STOPPED/ERROR agents back (re-sync existing tmux, or relaunch via `claude --resume`).\n- **Retry instead of rewrite**: Try → Summarize → Retry auto-generates what was tried; the next agent picks up with it in context. Durable lessons roll into per-project `PROGRESS.md` and are re-surfaced via RAG.\n- **Rich content + cheap cross-references**: inline rendering for images, PDFs, media, and LaTeX (KaTeX). Agents reference each other's sessions via a built-in MCP server, ~54× fewer tokens than raw JSONL.\n\n`claude` still runs the show. Xylocopa is the task, attention, and memory layer around it.\n\n### Lessons Compound\n\n**Agents miss. Xylocopa makes the loop after the miss part of the workflow.** Most agent tools assume the agent gets it right. Xylocopa assumes it won't. One click turns a miss into a summary, the next agent picks up from there, and the durable lessons accumulate per project in `PROGRESS.md`, not per session.\n\n### Zero Migration Cost\n\nXylocopa wraps the same `claude` CLI you already use, launched inside tmux sessions on your machine. Your CLAUDE.md files, project setup, and workflow carry over. The only new dependencies are **tmux** and optionally **Tailscale** for remote access. No new APIs, no lock-in.\n\n### Built for Reliability\n\nXylocopa hooks into Claude Code's native event system (no polling, no heuristics). Message delivery uses stop-hook dispatch with guaranteed ordering; session lifecycle is tracked via SessionStart/SessionEnd. Each agent runs in its own tmux session on a dedicated git worktree. A deterministic `PreToolUse` [safety hook](#safety-guardrails) hard-blocks destructive operations even under `--dangerously-skip-permissions`.\n\n### Durable by Default\n\nNothing you run through Xylocopa is ephemeral. Every layer is designed to survive restarts, crashes, and process kills:\n\n- **30s incremental session cache** ([`session_cache.py`](orchestrator/session_cache.py)): active JSONL is append-only-cached like git packfiles; truncated lines auto-repaired on restore.\n- **Unlimited retention**: sets `cleanupPeriodDays=36500` in `~/.claude/settings.json` so Claude Code never deletes history.\n- **Tmux-anchored recovery**: agents with live tmux panes are re-linked without interruption on restart, your agents survive the web app.\n- **One-click resume** ([`routers/agents.py`](orchestrator/routers/agents.py)): STOPPED/ERROR agents resume via re-sync or `claude --resume`.\n- **Periodic backups** ([`backup.py`](orchestrator/backup.py)): DB + configs + session history, runtime-configurable interval and retention.\n- **Local draft persistence** ([`useDraft.js`](frontend/src/hooks/useDraft.js)): every text input caches to `localStorage` across 13+ surfaces.\n- **Orphan cleanup** ([`orphan_cleanup.py`](orchestrator/orphan_cleanup.py)): stale worktrees, zombie tmux, and tempfiles from dead processes are swept periodically.\n\n\u003e Every bullet is open source and linked to its implementation. Audit it, don't trust it.\n\n## Features\n\n### Highlights\n\n- **Try → Summarize → Retry**: when an agent misses the mark, one click captures what was tried; the next dispatch picks up from there instead of starting cold.\n- **RAG-powered context**: new agents are seeded with relevant lessons from past sessions in the same project, retrieved automatically at dispatch time.\n- **Dual-directional CLI sync**: every agent runs in a tmux session you can attach to from your terminal; sessions you start in the CLI also appear in the web UI.\n- **Crash-proof by design**: 30s incremental session cache, partial output salvage on restart, unlimited session retention, and one-click resume of stopped agents. Your work survives the app. See [Durable by Default](#durable-by-default).\n- **Deterministic [safety hook](#safety-guardrails)**: `PreToolUse` hard-blocks destructive commands (`rm -rf`, force-pushes, `DROP TABLE`, out-of-project writes), even when agents run with `--dangerously-skip-permissions`.\n\n### Full feature list\n\n| Category | What you get |\n|---|---|\n| **Smart Notifications** | Hook-based notification system with dual-channel in-use detection, automatically notifies when you're away and stays quiet when you're present. Web Push (VAPID). Per-agent mute, global toggles. |\n| **Task Management** | Inbox with drag-to-reorder. Voice input. Lightning capture. Draft persistence. Per-project organization. Retry with auto-summarization. |\n| **Agent Control** | Start, stop, **one-click resume** of STOPPED/ERROR agents (re-sync to existing tmux or relaunch via `claude --resume`). Per-agent model selection (Opus/Sonnet/Haiku). Configurable timeouts and permission modes. AI batch dispatch. RAG-powered context from past sessions. Cross-session reference via MCP, agents read each other's curated display files (~54× fewer tokens than raw JSONL), keeping cross-references fast and context-window-friendly. **Context usage pill** with breakdown (system/tools/MCP/messages/cache) read from session JSONL. Per-agent **lifetime cost** tracking. **Subagent visibility**: `Agent`-tool sub-sessions discovered under `\u003csession\u003e/subagents/` and surfaced in a Task → Xylo → CC → Sub-session hierarchy. **System / meta-agents** (Task-AI, merge, etc.) hosted on a synthetic `.xylo-internal` placeholder, no longer required to be bound to a real project. |\n| **Chat Interface** | Rich markdown rendering (code blocks, tables, images). Inline media preview. Plan mode with approve/reject. Interactive tool confirmation cards. |\n| **Monitoring** | Split screen (up to 4 panes). Real-time WebSocket streaming. System monitor (disk, memory, GPU, tokens). Weekly progress stats. |\n| **Mobile PWA** | Add to Home Screen on iOS/Android. Full functionality, voice input, push notifications, task management. **E-ink display mode** (manual toggle in Settings → Display, plus auto-detect for BOOX / Onyx / Kindle / Bigme / Hisense / Meebook / iReader user agents) for high-contrast rendering on e-paper readers. |\n| **CLI Session Sync** | Dual-directional: CLI sessions in the web app, web app sessions resumable from CLI. |\n| **Git Integration** | Commit history, diffs, branch status per project. Agents work in isolated worktrees. One-click cleanup and push. |\n| **Session History** | Every conversation persisted and searchable. Star sessions. Resume any agent anytime. Full-text search. |\n| **Bookmarks** | Double-tap a chat bubble → **Bookmark** to save standout turns. Each bookmark stores your optional note plus a `gpt-4o-mini`-generated summary + emoji, plus media references extracted from the bubble and ±2 neighboring turns. Per-project **Bookmarks** section, tap a row for focus-flash navigation back to the original turn. |\n| **Security** | Password auth with exponential-backoff rate limiting. Inactivity lock. HTTPS encryption. |\n| \u003ca id=\"safety-guardrails\"\u003e\u003c/a\u003e**Safety Guardrails** | Deterministic `PreToolUse` hook hard-blocks destructive operations, `rm -rf`, `git push --force`, `git reset --hard` outside worktrees, `git clean -f`, `git checkout -- .` / `git restore .`, `DROP TABLE` / `TRUNCATE`, and any `Write`/`Edit` to paths outside the project directory. Enforced even when **Auto mode** (`--dangerously-skip-permissions`) is on. |\n| **Reliability \u0026 Recovery** | 30s incremental session JSONL cache (append-only, like git packfiles). **Unlimited retention**: `cleanupPeriodDays=36500` prevents Claude from deleting your history. Orchestrator-restart recovery re-links live tmux agents without interrupting them. Automatic periodic DB + config + session backups (runtime-configurable interval \u0026 retention). Truncated JSONL auto-repaired. Orphan worktree/tmux cleanup. See [Durable by Default](#durable-by-default) for source pointers. |\n\n## Before You Install\n\nA few things worth knowing before running this on your dev machine.\n\n### Where does my data live?\n\n- **SQLite DB**: `data/orchestrator.db` in the install directory (tasks, projects, agent metadata, configs)\n- **Agent sessions**: `~/.claude/projects/\u003cencoded-path\u003e/*.jsonl` (Claude Code's native session JSONL; Xylocopa doesn't duplicate these)\n- **Per-project memory**: `\u003cproject\u003e/PROGRESS.md` inside each project's git repo\n- **Backups**: `backups/` (rolling DB + session snapshots, see [Durable by Default](#durable-by-default))\n- **Uploaded files**: `~/.xylocopa/uploads/`\n\nTo capture everything in one snapshot, back up the install directory and `~/.claude/projects/` together.\n\n### How do I uninstall it?\n\n```bash\n# Stop the services\npm2 delete xylocopa-backend xylocopa-frontend \u0026\u0026 pm2 save\n\n# Remove the install\nrm -rf ~/xylocopa-main          # or wherever you cloned it\nrm -rf ~/.xylocopa              # uploaded files\n\n# Optional: remove your project directories too\nrm -rf ~/xylocopa-projects\n\n# Optional: restore Claude Code's default session-cleanup window\n# (Xylocopa sets cleanupPeriodDays=36500 in ~/.claude/settings.json)\n```\n\nProject code, git history, and Claude Code session JSONL files in `~/.claude/projects/` are untouched by the uninstall.\n\n## Getting Started\n\n### Host Setup\n\n#### Prerequisites\n\n- **Linux** or **macOS** host (Ubuntu 22.04+ / macOS 13+ recommended)\n- **Node.js** 18+ and npm\n- **Python** 3.11+\n- **tmux** (usually pre-installed; `sudo apt install tmux` if not)\n- **Claude Code CLI**: `npm install -g @anthropic-ai/claude-code`, then run `claude` once interactively to log in (Xylocopa reuses the credentials in `~/.claude/`). On a headless server with no browser, use `claude setup-token` instead.\n- **Claude subscription**: Claude Max or Pro (uses your existing subscription, no separate API billing)\n- **OpenAI API key** _(optional, for voice input)_\n\n#### Third-party / Local Models *(optional)*\n\nClaude Code itself supports Amazon Bedrock, Google Vertex AI, and LLM gateways like LiteLLM (which can front local models such as Llama). Configure it the standard way — set the relevant environment variables in your shell or in `.env`. Xylocopa launches `claude` as a subprocess and inherits them transparently. A practical walkthrough (LiteLLM + local models with Claude Code) is at [unsloth.ai/docs/basics/claude-code](https://unsloth.ai/docs/basics/claude-code).\n\n\u003e **Heads-up on UI scope:** Xylocopa's model dropdown is hardcoded to Anthropic's `claude-*` model IDs (Opus / Sonnet / Haiku). Bedrock / Vertex generally just work because they reuse the same model names. For non-Anthropic backends (LiteLLM → Llama, etc.), you can still run them via the `CC_MODEL` default in `.env`, but per-agent model switching from the UI isn't wired up. Exposing a custom-model field is a small tweak (`frontend/src/lib/constants.js` + `VALID_MODELS` in `orchestrator/config.py`), but it's outside Xylocopa's maintained scope.\n\n#### Installation\n\nFastest path (clones + runs the interactive installer):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/jyao97/xylocopa/master/setup.sh | bash\n```\n\nThis installs into `~/xylocopa-main` and prompts for your projects directory, default Claude model, OpenAI API key (optional), and ports. It writes `.env`, generates SSL certs, installs Python and Node dependencies, and launches the services. No manual `.env` editing required.\n\nIf you prefer to clone manually:\n\n```bash\ngit clone https://github.com/jyao97/xylocopa.git ~/xylocopa-main\ncd ~/xylocopa-main\n./setup.sh        # same interactive prompts as above\n./run.sh start\n```\n\nVerify by opening `https://\u003cmachine-ip\u003e:3000` on the host. Find your machine's LAN IP with `hostname -I` on Linux or `ipconfig getifaddr en0` on macOS.\n\n\u003e **Tip:** You can also run `claude` in an empty directory and tell it to set up Xylocopa for you :)\n\n\u003e **Tip:** Symlink the Xylocopa repo into `~/xylocopa-projects/` to personalize your experience, let agents improve the tool while you use it.\n\n#### Auto-Start on Reboot (PM2)\n\nStrongly recommended, not just for reboot survival: this step also moves the pm2 daemon out of the terminal session that spawned it. On Linux that matters because systemd-oomd can SIGKILL an entire terminal cgroup (e.g. GNOME Terminal's `vte-spawn-*.scope`) under memory pressure, taking backend+frontend with it. On macOS the equivalent benefit is that pm2 no longer dies if you close Terminal.app.\n\n```bash\n./run.sh startup\n```\n\nThis runs `pm2 save` + `pm2 startup` with auto-detection (systemd on Linux, launchd on macOS). On Linux it will print a `sudo env PATH=... pm2 startup systemd ...` line, copy and run it exactly as shown. On macOS no sudo is needed.\n\nTo disable later: `pm2 unstartup` (same auto-detection).\n\n#### Set Up Your Projects\n\nAdd projects in the app: **long-press the + button → New Project**: paste any GitHub URL or point to an empty folder. You can also manually create or symlink folders in the projects directory (`~/xylocopa-projects/` by default, configured via `HOST_PROJECTS_DIR` in `.env`).\n\n### Client Setup\n\nAfter setting up the host, visit `https://\u003cmachine-ip\u003e:3000` from any device with network access, that's it. Set a password on first visit.\n\n#### Remote Access\n\nFor access outside your LAN, Xylocopa works with any tunneling or VPN solution, [Tailscale](https://tailscale.com), [ZeroTier](https://www.zerotier.com), [WireGuard](https://www.wireguard.com), [frp](https://github.com/fatedier/frp), Cloudflare Tunnel, etc. The author uses Tailscale:\n\n1. Install [Tailscale](https://tailscale.com) on your server and phone\n2. `tailscale up` on both devices\n3. Access Xylocopa at `https://\u003ctailscale-ip\u003e:3000`\n\nNo port forwarding, no public exposure, traffic stays in an encrypted tunnel between your devices.\n\n#### iPhone PWA\n\nIf you want the full app experience on iPhone (home screen icon, fullscreen, push notifications):\n\n1. Open `https://\u003cmachine-ip\u003e:3000` in Safari (bypass the certificate warning via **Advanced → Visit Website**, then refresh).\n2. Follow the on-screen guide on the login page to install the CA certificate and the Xylocopa app.\n\n#### Installing the CA Certificate\n\nXylocopa uses a self-signed SSL certificate. The host trusts it after setup, but other client devices will show a browser warning until you install the cert. iPhone/iPad users can skip this, the [iPhone PWA](#iphone-pwa) guide above already covers it.\n\nFor Android, macOS, Windows, and Linux, see [detailed instructions](docs/install-cert.md).\n\n## Telemetry\n\nXylocopa sends **one anonymous event per day** — `daily_heartbeat` — to help me see if the project is being used. Payload: random `install_id` (UUID v4 generated locally), `version`, `platform` (`darwin` / `linux` / `win32`), `timestamp`. **That's everything.** No IPs, no prompts, no code, no file paths, no hostnames, nothing user-generated.\n\nClient: [`orchestrator/telemetry.py`](orchestrator/telemetry.py) — sends to a Cloudflare Worker the author owns ([source](https://github.com/jyao97/xylocopa-telemetry)) that writes to a private D1 database. No third-party analytics.\n\n**Disable** (any one is enough): toggle off in **Monitor → Help improve Xylocopa**, or set `XYLOCOPA_TELEMETRY=0`, or write `telemetry: false` in `~/.xylocopa/config.yaml`.\n\n## Gestures \u0026 Shortcuts\n\n- **Short-press the + button** to quickly add a task. **Long-press** it to choose between adding a project, agent, or task.\n- **Long-press a card** (Inbox task, Agent row, Project tile, or row inside a Project / Trash list) to enter multi-select mode — the pressed card is pre-selected. Tap others to add/remove, then use the bottom bar to bulk-act. Tap **Done** in the header to exit.\n- **Inbox**: AI batch-process / Start / Delete the selection.\n- **Agents** (and inside a Project's agent tab): mark Read / Stop / Delete the selection — including stopping or deleting agents in bulk (no per-row delete button; long-press is the entry point).\n- **Projects**: Activate / Archive / Delete; the Activate and Archive buttons light up only when the selection is uniformly archived or active, otherwise only Delete is available.\n- **Trash**: bulk Restore / permanently Delete deleted projects.\n- **ID pill** in the chat header (4-char monospace, row 2): hover or long-press for a `xylo id:` popover with a Copy button; double-click to copy directly. Same pattern on the **worktree pill**.\n- **Double-tap a message** in the chat view to open its action menu — Copy / Modify / Delete / Bookmark. Only one menu is open at a time; an outside tap dismisses. **Bookmark** opens an inline note prompt; skip it and the AI-generated summary is used as the title.\n- **Double-tap a tab** in the bottom nav to scroll to the first unread / pending item.\n\n## Agent control plane\n\nXylocopa-managed agents can call back into the orchestrator via a built-in\nMCP server — list/create/dispatch tasks, read each other's sessions,\nscaffold projects, check health. The surface is deliberately\nnon-destructive (verb whitelist + blacklist).\n\nSee **[docs/agent-mcp-tools.md](docs/agent-mcp-tools.md)** for the full\ntool list, safety model, and what's intentionally not exposed.\n\n## Troubleshooting\n\n- **Conversation stuck or not updating?** Click the **refresh button** at the top of the chat view to re-sync the session from the CLI.\n- **Agent shows IDLE after server restart but is still running?** Normal. Status restores to EXECUTING on the next tool call (heartbeat via the `agent-tool-activity` hook). Send a message to trigger activity if it's in a long thinking phase.\n- **Don't name tmux sessions with the `xy-` or `ah-` prefix** — those are Xylocopa's managed prefixes (`xy-{id}`; legacy `ah-{id}` still recognized). User-created sessions with those prefixes won't be detected.\n- **PWA stuck on a perpetual loading screen?** Stale Service Worker precache. Run `.venv/bin/python tools/push_reset.py` on the host for an interactive picker (lists devices with labels and last-ack times; `a` resets all, `q` quits). Then fully close the PWA on the device and reopen it. Direct forms `list`/`\u003csub_id\u003e`/`all` are supported for scripting.\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Reporting bugs and suggesting features\n- Setting up a development environment\n- Running tests and submitting pull requests\n\n## Migration from AgentHive\n\nXylocopa was previously named **AgentHive**. The upgrade is backward compatible, no manual migration needed:\n\n- **CLI**: `agenthive` stays as a symlink to `xylocopa`.\n- **Install dir / env vars**: `AGENTHIVE_DIR` and `AGENTHIVE_MANAGED` still honored alongside the new `XYLOCOPA_*` names. `~/agenthive-main` checkouts keep working.\n- **Process names**: `pm2` processes are now `xylocopa-backend` / `xylocopa-frontend` (upgrade script removes the legacy `agenthive-*` entries).\n- **MCP / tmux**: `.mcp.json` entry renamed to `xylocopa` on first agent start; new agents use `xy-{id}` prefix, legacy `ah-{id}` sessions are still recognized so in-flight agents survive.\n- **Data dirs**: `~/.agenthive/uploads` auto-renames to `~/.xylocopa/uploads` on first backend start (if the new path doesn't exist).\n- **Browser / certs / Web Clip**: `localStorage` keys auto-migrate on first page load; existing certs keep working; re-download `Xylocopa.mobileconfig` from the login page if you want the renamed Home Screen entry.\n\nTo rename your install dir: `mv ~/agenthive-main ~/xylocopa-main \u0026\u0026 cd ~/xylocopa-main \u0026\u0026 ./run.sh restart`.\n\n## License\n\nApache 2.0, see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjyao97%2Fxylocopa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjyao97%2Fxylocopa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjyao97%2Fxylocopa/lists"}