{
  "markdown": "# githubclip\n\nGitHub-backed agent orchestration for Claude Code. A single Claude instance wears different \"hats\" (personas) based on GitHub issue labels – an Orchestrator routes work, a CEO makes strategic calls, and worker personas execute.\n\n## How It Works\n\n```\nGitHub Issues → /heartbeat → Persona Matching → Work → Report Back\n```\n\n1. **Issues** live in a GitHub Project with persona labels (`backend`, `frontend`, etc.)\n2. **Heartbeat** picks the highest-priority issue and resolves which persona handles it\n3. **Personas** (CEO, Backend, Frontend, ...) define identity, tools, and runtime config\n4. **Reports** are structured comments on the GitHub issue with progress, commits, and blockers\n5. **Schedule** runs heartbeats automatically via Claude Code's `/schedule`\n\nThe human is the **Board** – the ultimate escalation target when the agent is blocked.\n\n## Install\n\nIn Claude Code, add and install from this marketplace:\n\n```bash\n/plugin marketplace add gvzq/githubclip\n/plugin install githubclip@githubclip\n```\n\nOr use the UI: run `/plugin` → **Add Marketplace** → enter `gvzq/githubclip`, then install `githubclip`.\n\nOr for local development:\n\n```bash\ngit clone https://github.com/gvzq/githubclip.git\nclaude --plugin-dir /path/to/githubclip\n```\n\n### Prerequisites\n\n- [Claude Code](https://claude.ai/code) installed\n- **[GitHub plugin](https://claude.ai/marketplace)** installed from the Claude marketplace — search for `claude-plugins-official / GitHub` and enable it. This provides the GitHub MCP integration githubclip depends on.\n\n  Alternatively, connect GitHub MCP manually by adding to your `.mcp.json` or global MCP config:\n  ```json\n  {\n    \"mcpServers\": {\n      \"github\": {\n        \"type\": \"stdio\",\n        \"command\": \"github-mcp-server\",\n        \"args\": [\"stdio\"],\n        \"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"<your-token>\" }\n      }\n    }\n  }\n  ```\n- GitHub repository with a GitHub Project v2 (with `Status` and `Priority` custom fields)\n- Issues assigned to your GitHub account\n\n## Quick Start\n\n```bash\n# 1. Initialize githubclip in your repo (creates config + personas + labels)\n/githubclip-init\n\n# 2. Run a single heartbeat cycle\n/heartbeat\n\n# 3. Or schedule recurring heartbeats\n/schedule 30m /heartbeat\n\n# 4. Check status\n/githubclip-status\n```\n\n## The Heartbeat Loop\n\nEach `/heartbeat` runs an 11-step cycle:\n\n1. **Load config** – read `.githubclip/config.yaml`, check lockfile\n2. **Check inbox** – query GitHub Project for assigned issues, filter and sort\n3. **Pick issue** – highest priority In Progress, then Todo\n4. **Resolve persona** – match issue label → persona directory, load SOUL.md + TOOLS.md\n5. **Validate tools** – check required MCP tools are available\n6. **Lock issue** – add `agent-working` label\n7. **Understand context** – read issue, comments, heartbeat counter\n8. **Do work** – follow persona instructions (CEO triages, workers implement)\n9. **Report** – post structured comment with progress, commits, sub-issues\n10. **Update state** – manage Project status and labels based on outcome\n11. **Next or exit** – pick another issue or clean up and stop\n\nUse `--dry-run` to see what would be picked without doing work. Use `--persona backend` to force a specific persona.\n\n## Personas\n\nEach persona gets its own directory with three files:\n\n| File | Purpose |\n|------|---------|\n| `SOUL.md` | Identity, posture, voice, decision framework |\n| `TOOLS.md` | Available tools and integrations |\n| `config.yaml` | Runtime config (model, thinking effort, max turns) |\n\n### Default Personas\n\n| Persona | Role | Model | Turns | Label |\n|---------|------|-------|-------|-------|\n| Orchestrator | Route issues, decompose work | Haiku | 50 | *(default – no label)* |\n| CEO | Strategy, prioritization, architecture | Sonnet | 100 | `ceo` |\n| Backend | API, database, server-side | Opus | 300 | `backend` |\n| Frontend | UI, components, styling | Sonnet | 200 | `frontend` |\n\nCreate custom personas with `/persona-create` or copy directories between repos.\n\n### Per-Repo Structure\n\nAfter `/githubclip-init`, your repo gets:\n\n```\n.githubclip/\n├── config.yaml              # GitHub settings, heartbeat behavior, persona routing\n├── heartbeat-log.jsonl      # Append-only heartbeat history (created at runtime)\n└── personas/\n    ├── orchestrator/\n    │   ├── SOUL.md\n    │   ├── TOOLS.md\n    │   └── config.yaml\n    ├── ceo/\n    │   ├── SOUL.md\n    │   ├── TOOLS.md\n    │   └── config.yaml\n    ├── backend/\n    │   ├── SOUL.md\n    │   ├── TOOLS.md\n    │   └── config.yaml\n    └── frontend/\n        ├── SOUL.md\n        ├── TOOLS.md\n        └── config.yaml\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/heartbeat` | Run one heartbeat cycle |\n| `/heartbeat --dry-run` | Show what would be picked up |\n| `/heartbeat --persona backend` | Force a specific persona |\n| `/githubclip-init` | Initialize githubclip in a repo |\n| `/githubclip-status` | Current state, queue, blocked issues |\n| `/githubclip-status --history` | Recent heartbeat history |\n| `/persona-create` | Create a new persona interactively |\n| `/persona-list` | List configured personas |\n\n## Label System\n\ngithubclip uses GitHub labels for state management:\n\n| Label | Purpose |\n|-------|---------|\n| `agent-working` | Agent is actively working this issue |\n| `agent-blocked` | Agent is blocked, needs Board attention |\n| `backend`, `frontend`, etc. | Routes issue to the matching persona |\n\nAll labels are created under a `githubclip` group by `/githubclip-init`.\n\n## Schedule Cadences\n\n| Workload | Cadence | Command |\n|----------|---------|---------|\n| Active sprint | Every 15-30 min | `/schedule 15m /heartbeat` |\n| Steady state | Every 1-2 hours | `/schedule 1h /heartbeat` |\n| Background | Every 4-6 hours | `/schedule 4h /heartbeat` |\n| Manual only | No schedule | `/heartbeat` when needed |\n\n## Migrating from Paperclip\n\nUse `/persona-import` to convert Paperclip agent directories into githubclip personas. It maps SOUL.md, TOOLS.md, HEARTBEAT.md role-specific sections, and AGENTS.md safety rules into the githubclip format. Budget tracking, PARA memory, and approval workflows are not imported (replaced by Claude Code built-in features or intentionally omitted from v1).\n\n## Background\n\ngithubclip is a fork of [woterclip](https://github.com/wotai/woterclip), which was itself inspired by [Paperclip](https://github.com/paperclipai/paperclip) — an agent orchestration platform that uses a central API for task management, agent checkout, and chain-of-command routing. githubclip takes the same core ideas – persona-based identity, structured heartbeats, hierarchical escalation – and rebuilds them as a Claude Code plugin backed by GitHub instead of a custom API. The result is simpler (no server, no database, no separate processes) while keeping the parts that worked well: SOUL.md for agent identity, structured comments for audit trails, and a CEO/worker hierarchy for task decomposition.\n\n## Design\n\nSee [`docs/specs/2026-03-25-githubclip-design.md`](docs/specs/2026-03-25-githubclip-design.md) for the full design spec and [`docs/specs/2026-03-25-githubclip-implementation-plan.md`](docs/specs/2026-03-25-githubclip-implementation-plan.md) for the build order.\n\n## License\n\nMIT\n",
  "bytes": 7220,
  "sha": "3d4e6c051a039944e2877d5454926355de47918633251e76135d33eec3830214",
  "repo_slug": "gvzq/githubclip",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_gvzq_githubclip_githubclip_fb7c7790/readme"
}