{
  "markdown": "<!-- mcp-name: io.github.bepunk/zoogent -->\n\n# ZooGent\n\nLightweight AI agent orchestrator with built-in Architect AI. Multi-team support - run isolated agent teams in a single instance. Describe what you want to automate, get working agents.\n\n## Quick Start\n\n```bash\nnpx zoogent create my-agents\ncd my-agents\nnpx zoogent start\n```\n\nOpen http://localhost:3200. Create account > create team > add Anthropic API key in Team Settings > go to Architect and describe what you want to automate.\n\n## What is ZooGent\n\nZooGent is a process manager for AI agent teams. It spawns agents, routes tasks between them, tracks costs, and captures logs. Each agent is a standalone script that calls its own LLM.\n\n**Multi-team isolation** - one instance, multiple teams. Each team has its own agents, skills, memory, knowledge, Architect chat, and API keys. Teams don't see each other's data.\n\n**Two ways to use it:**\n\n1. **Chat UI** - open the Architect page in your browser, describe your task in plain language. The Architect AI designs the team, creates skills, writes agent code, and tests everything.\n\n2. **Claude Code + MCP** - connect MCP to Claude Code, build agents from the terminal with full control over code and configuration.\n\nBoth paths use the same API, same database, same agents. Pick whichever fits your workflow.\n\n## Getting Started\n\n### Path 1: Web UI + Architect\n\n#### Local\n\n```bash\nnpx zoogent create my-agents\ncd my-agents\nnpx zoogent start\n```\n\n1. Open http://localhost:3200\n2. Create your account\n3. Create a team\n4. Go to Team Settings > add your Anthropic API key\n5. Go to **Architect** > describe what you want to automate\n\nArchitect designs agents, writes skills, generates code, and tests everything through conversation.\n\n#### Server\n\n```bash\nnpx zoogent create my-agents\ncd my-agents\nnpx zoogent start -d\n```\n\nSet `BETTER_AUTH_URL` to your public URL in `.env`. Use a reverse proxy (nginx, Caddy) or deploy via Docker (see [Deployment](#deployment) section). The web UI is the same - just accessed remotely.\n\n### Path 2: Claude Code + MCP\n\n#### Local\n\nStart the server locally, then connect Claude Code via MCP:\n\n```bash\nnpx zoogent create my-agents\ncd my-agents\nnpx zoogent start -d\n```\n\nAdd the MCP server to Claude Code. Run this **from inside the project you want to work in** — each project typically binds to its own ZooGent instance (its own SQLite, teams, agents, API keys), so the MCP config should live with the project:\n\n```bash\nclaude mcp add zoogent -s project -- npx zoogent mcp\n```\n\n`-s project` writes the config to `.mcp.json` in the project root — commit it and teammates who clone the repo get the same MCP setup automatically.\n\nClaude Code auto-discovers the local server. Ask Claude to create a team and design your agents.\n\n#### Remote server\n\nDeploy ZooGent to a server (see [Deployment](#deployment)). Open the web UI, create an account, go to Settings > generate an API key.\n\nRun from inside the project that should connect to this ZooGent instance:\n\n```bash\nclaude mcp add zoogent -s project \\\n  -e ZOOGENT_URL=https://your-domain.com \\\n  -e ZOOGENT_API_KEY=zg_your-key-from-settings \\\n  -- npx zoogent mcp\n```\n\n> Each project can point at its own ZooGent (local or remote), with its own URL and API key. Keeping the config in the project's `.mcp.json` makes that mapping explicit. Use `-s user` instead only if you have a single shared ZooGent instance across all projects.\n\n<details>\n<summary>Alternative: configure via .mcp.json</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"zoogent\": {\n      \"command\": \"npx\",\n      \"args\": [\"zoogent\", \"mcp\"],\n      \"env\": {\n        \"ZOOGENT_URL\": \"https://your-domain.com\",\n        \"ZOOGENT_API_KEY\": \"zg_your-key-from-settings\"\n      }\n    }\n  }\n}\n```\n</details>\n\nClaude Code connects to the remote server. Create teams, design agents, write code - all through MCP tools. Agents run on the server.\n\n## How It Works\n\n1. Create a team for your business process\n2. Describe what you want automated in the team's Architect chat\n3. Architect creates agents (with goals, schedules, models) and writes their code\n4. Agents run on schedule or by event, communicate through tasks\n5. Agents learn from experience (Memory) and share knowledge (Team Knowledge)\n6. When something breaks, Architect sees the error logs and suggests fixes\n\n### Examples\n\n**Social media monitoring.** Scout agent scans Reddit and Hacker News every 2 hours for relevant posts. Comment writer drafts responses in the right tone. Feedback collector checks next day - which comments got upvotes, which got ignored. Team learns and adapts.\n\n**Invoice processing.** Watcher agent polls an email inbox for new invoices. Parser extracts amounts, dates, vendor info. Router creates entries in your accounting system via API. Anomaly detector flags invoices that look unusual for human review.\n\n**Customer support automation.** Intake agent receives customer requests via webhook. Analyzer classifies urgency and type, creates tasks for human team members in your project tracker. Follow-up agent monitors task completion, notifies customers when their request is resolved.\n\n## Features\n\n### Teams\nMultiple isolated teams in one instance. Each team has its own agents, skills, memory, knowledge, Architect chat, and Anthropic API key. Header nav: Teams / Members / Settings. Team sub-nav: Architect / Agents / Tasks / Costs / Skills / Memory / Knowledge / Settings.\n\n### Architect AI\nBuilt-in Claude-powered chat that designs and manages your agent team. Creates agents, writes skills, generates TypeScript code, assigns skills, triggers runs, reads logs - all through conversation. SSE streaming with real-time tool execution display. Each team has its own Architect with separate chat history.\n\n### Agent Runtimes\n\n| Runtime | Source of code | When to use |\n|---------|----------------|-------------|\n| `typescript` (default) | Stored in zoogent DB, uploaded via MCP/chat, bundled with esbuild | ~95% of agents — write/iterate from Claude Code, remote deploy just works |\n| `exec` | Lives outside zoogent; you provide `command` + `args` + `cwd` | Wrapping binaries, Python/Go scripts, existing tooling |\n\nFor `typescript`, agents can import from a curated blessed set: `@anthropic-ai/sdk`, `openai`, `@google/generative-ai`, `axios`, `cheerio`, `googleapis`, `zod`, `p-limit`/`p-retry`/`p-map`/`p-queue`, `date-fns`, `yaml`, `csv-parse`/`csv-stringify`, `cheerio`, `fast-xml-parser`, `marked`, `turndown`, `slugify`, `tiktoken`, `nodemailer`, `imapflow`, `mailparser`, `jsonwebtoken`, plus all Node built-ins. Unknown imports fail at upload with a readable error. The full list lives in the `code-generation` system skill — call `get_agent_guide(\"code-generation\")` from MCP.\n\n### Agent Types\n\n| Type | How it runs | Example |\n|------|-------------|---------|\n| `cron` | On schedule | News scanner every 2 hours |\n| `manual` | On demand or via task | Content writer triggered by scanner |\n| `long-running` | Persistent process | Telegram bot, webhook listener |\n\n### 5 Communication Channels\n\n| Channel | What | Who sees it |\n|---------|------|-------------|\n| **Tasks** | Messages between agents | Sender + receiver |\n| **Team Knowledge** | Shared facts (moderated) | All agents in team |\n| **Memory** | Personal learnings | Only the agent |\n| **Store** | Persistent working data (URLs, IDs, state) | Only the agent |\n| **Skills** | Instructions from humans | Assigned agents |\n\n### Skills\nMarkdown documents with instructions and knowledge, stored in the database per team. Assigned to agents - injected into their context at startup. Create via Architect chat, MCP, or API. System skills (team-design, agent-patterns, code-generation, etc.) are global and used by Architect AI.\n\n### Agent Store\nKey-value storage for agent working data that persists between runs. Track URLs, save processed IDs, cache state. Optional TTL for auto-expiry.\n\n```typescript\nawait storeSet('seen_urls', ['https://...'], 604800); // expires in 7 days\nconst urls = await storeGet('seen_urls');\n```\n\n### Cost Tracking\nPer-agent and per-team spending. Monthly budgets with hard stops - agent won't run if over budget. Set team budget in Team Settings, per-agent budget in agent config.\n\n### Self-Healing\nWhen an agent fails, the error with stderr excerpt appears in the team's Architect chat. Open Architect, see what went wrong, ask it to fix the code.\n\n### Web Dashboard\nLight and dark themes. Global pages: Teams, Members, Settings. Team pages: Architect (chat), Agents, Tasks, Costs, Skills, Memory, Knowledge.\n\n## CLI Commands\n\n```bash\nzoogent create <name>  # Create new project (recommended)\nzoogent init           # Initialize in current directory\nzoogent start          # Start server (foreground)\nzoogent start -d       # Start server (daemon)\nzoogent stop           # Stop daemon\nzoogent status         # Check if running\nzoogent logs           # View server logs (-f to follow)\nzoogent mcp            # Start MCP server (stdio)\n```\n\n## Deployment\n\n### Server (no Docker)\n\n```bash\nnpx zoogent create my-agents\ncd my-agents\nnpx zoogent start -d\n```\n\n### Docker / Dokploy / Railway\n\nNo repository needed. Paste this compose into your hosting platform (Dokploy, Railway, etc.) and deploy.\n\n```yaml\nservices:\n  app:\n    image: node:24-slim\n    working_dir: /app\n    command: sh -c \"npm install zoogent@0.4.2 @anthropic-ai/sdk && npx zoogent init && npx zoogent start\"\n    expose:\n      - \"3200\"\n    environment:\n      - DATABASE_URL=./data/zoogent.db\n      - PORT=3200\n      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}\n      - BETTER_AUTH_URL=${BETTER_AUTH_URL}\n    volumes:\n      - zoogent-data:/app/data\n    restart: unless-stopped\n\nvolumes:\n  zoogent-data:\n```\n\nSet `BETTER_AUTH_SECRET` (generate: `openssl rand -hex 32`) and `BETTER_AUTH_URL` (your public URL) in the platform's environment settings.\n\nTo upgrade ZooGent: change `zoogent@0.4.2` to the new version and redeploy.\n\n### Required Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BETTER_AUTH_SECRET` | Yes | Session secret. `openssl rand -hex 32` |\n| `BETTER_AUTH_URL` | Remote only | Public URL (e.g., `https://your-domain.com`) |\n\n## Agent SDK\n\nTypescript agents use `zoogent/client` for context + task flow:\n\n```typescript\nimport {\n  // Tasks\n  createTask, getMyTasks, checkoutTask, completeTask, failTask,\n  // Reporting\n  reportCost, reportMemory, reportTeamKnowledge,\n  // Context\n  getGoal, getSkills, getMemories, getTeamKnowledge,\n  // Store\n  storeGet, storeSet, storeDelete, storeKeys,\n  // Skills\n  loadSkill, loadSkills,\n  // Consensus\n  submitEvaluation,\n  // Health\n  heartbeat,\n} from 'zoogent/client';\n```\n\nFor runtime=\"typescript\" agents, zoogent hosts these deps — your code just imports them.\nFor runtime=\"exec\" in any language, call the HTTP API directly: see the `/llms-agent-guide.txt` endpoint for the reporting contract.\n\nAll SDK calls are fail-open (errors caught silently). All functions read `ZOOGENT_*` env vars automatically.\n\n### Workflow\n\n```\n1. MCP: create_agent with source=<boilerplate> → zoogent bundles with esbuild, agent is ready\n2. MCP: trigger_agent + get_logs → test\n3. MCP: write_agent_code with new source → re-bundle, iterate\n```\n\nNo local `agents/` directory to keep in sync. Source of truth is zoogent's DB. On remote deploys,\nthe same MCP calls work against `ZOOGENT_URL` without any deployment step for the agent code itself.\n\n## Environment Variables\n\n### Server\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `DATABASE_URL` | SQLite file path | `./data/zoogent.db` |\n| `PORT` | Server port | `3200` |\n| `BETTER_AUTH_SECRET` | Session encryption key | Auto-generated |\n| `BETTER_AUTH_URL` | Public URL for auth | `http://localhost:3200` |\n\n### Injected into Agents\n\n| Variable | Description |\n|----------|-------------|\n| `ZOOGENT_API_URL` | Server URL |\n| `ZOOGENT_AGENT_ID` | Agent ID |\n| `ZOOGENT_AGENT_GOAL` | Agent's mission |\n| `ZOOGENT_AGENT_MODEL` | AI model |\n| `ZOOGENT_RUN_ID` | Current run ID |\n| `ZOOGENT_TEAM_ID` | Team ID |\n| `ZOOGENT_API_KEY` | API key (from Settings) |\n| `ZOOGENT_AGENT_SKILLS` | Required skills content |\n| `ZOOGENT_INTEGRATIONS` | Agent integrations (JSON) |\n| `INTEGRATION_{NAME}_{FIELD}` | Individual integration credentials |\n| `ZOOGENT_MEMORIES` | Past learnings (JSON, scored) |\n| `ZOOGENT_TEAM_KNOWLEDGE` | Shared knowledge (JSON) |\n| `ANTHROPIC_API_KEY` | From team settings (auto-injected) |\n\n## Tech Stack\n\n- **Runtime**: Node.js 24, TypeScript\n- **HTTP**: Hono (JSX SSR)\n- **Database**: SQLite (better-sqlite3, WAL, FTS5) + Drizzle ORM\n- **Auth**: Better Auth (email + password, sessions)\n- **AI**: Anthropic SDK (Claude for Architect)\n- **UI**: htmx + Tailwind CDN (server-rendered)\n- **MCP**: @modelcontextprotocol/sdk (stdio)\n- **Cron**: node-cron\n\n## Security\n\n- Agent env vars encrypted at rest (AES-256-GCM)\n- Per-team settings (API keys) encrypted in database\n- API keys managed in Settings UI (multiple named keys, stored in DB)\n- Unified auth: localhost bypass + API key (from DB) + session cookie\n- Path traversal protection on skill paths\n- Log sanitization (strips API keys from stdout/stderr)\n- First user = owner, registration closed after setup\n- Team isolation: agents, skills, memory, knowledge scoped per team\n- **Agent sandbox**: TypeScript agents always run with Node.js 24 `--permission`. Write access restricted to the team shared folder (`ZOOGENT_SHARED_DIR = data/teams/{id}/shared/`). No child_process spawning, no native addons. `--max-old-space-size=512` applied.\n- **Shared team folder**: `data/teams/{id}/shared/` — agents in the same team can exchange files (images, video, CSVs) without cloud storage. Persists across restarts if `data/` is mounted as a Docker volume.\n\n## License\n\nMIT\n",
  "bytes": 13784,
  "sha": "8f06c104beba29e50503233c8d0e48768b3d59acf52423ebb230b0f36fdbb880",
  "repo_slug": "bepunk/zoogent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bepunk_zoogent_69cec296/readme"
}