{"skill":{"slug":"codebase-guide","displayName":"Codebase Guide","summary":"Use for every task involving this project. Covers running Ganglion, its CLI commands, HTTP bridge API, pipeline execution, knowledge queries, configuration,...","description":"---\nname: codebase-guide\ndescription: \"Use for every task involving this project. Covers running Ganglion, its CLI commands, HTTP bridge API, pipeline execution, knowledge queries, configuration, and operational workflows. Trigger phrases: 'run the pipeline', 'start the server', 'check status', 'query knowledge', 'configure', 'call the API', 'scaffold a project', 'check metrics', 'rollback', 'swap policy'.\"\nhomepage: https://github.com/TensorLink-AI/ganglion\nmetadata: {\"openclaw\": {\"emoji\": \"📘\", \"requires\": {\"bins\": [\"python3\", \"ganglion\"], \"env\": [\"OPENAI_API_KEY\"]}, \"always\": true}}\n---\n\n# Ganglion — Operator's Manual\n\nGanglion is a domain-specific execution engine for Bittensor subnet mining. It provides a pipeline framework for orchestrating autonomous mining agents that search for optimal model configurations. It exposes a CLI, an HTTP bridge API, and a Python library. Ganglion is search infrastructure — it doesn't know what a good model looks like, it knows how to search for one.\n\n## Quick Reference\n\n```bash\n# Scaffold a new project\nganglion init ./my-subnet --subnet sn9 --netuid 9\n\n# Check state (local mode)\nganglion status ./my-subnet\nganglion tools ./my-subnet\nganglion agents ./my-subnet\nganglion knowledge ./my-subnet --capability training --max-entries 10\nganglion pipeline ./my-subnet\n\n# Run (local mode)\nganglion run ./my-subnet\nganglion run ./my-subnet --stage plan\nganglion run ./my-subnet --overrides '{\"target_metric\":\"accuracy\"}'\n\n# Start HTTP bridge (remote mode)\nganglion serve ./my-subnet --bot-id alpha --port 8899\n\n# Check state (remote mode)\ncurl -s \"$GANGLION_URL/v1/status\" | jq .data\n```\n\n## Mode Detection\n\nGanglion supports two modes. **Always check which mode applies before running commands.**\n\n- **Local mode**: No `GANGLION_URL` set, or `GANGLION_PROJECT` is set. Use `ganglion <command> <project_dir>` directly.\n- **Remote mode**: `GANGLION_URL` is set. Use `curl` against the HTTP bridge.\n\n```bash\nif [ -n \"$GANGLION_PROJECT\" ] || [ -z \"$GANGLION_URL\" ]; then\n  echo \"local\"\nelse\n  echo \"remote\"\nfi\n```\n\n## Response Format\n\nAll HTTP bridge endpoints (except health probes) return responses in a standard envelope:\n\n- **Success**: `{\"data\": <payload>}` — use `jq .data` to extract\n- **Error**: `{\"detail\": {\"error\": {\"code\": \"ERROR_CODE\", \"message\": \"...\"}}}`\n\nHealth probes (`/healthz`, `/readyz`) return raw JSON without the envelope.\n\nInteractive API docs: `$GANGLION_URL/v1/docs` (Swagger UI).\n\n> **Note:** Unversioned routes (e.g. `/status`) still work but are deprecated. Always use `/v1/`.\n\n## How to Run\n\n**Prerequisites:** Python >= 3.11, `OPENAI_API_KEY` set (used by the LLM runtime).\n\n**Install:** `pip install ganglion`\n\n**Scaffold a project:**\n```bash\nganglion init ./my-subnet --subnet sn9 --netuid 9\n```\nThis creates `config.py`, `tools/`, `agents/`, and `skill/` in the target directory.\n\n**Start in local mode:**\n```bash\nexport GANGLION_PROJECT=./my-subnet\nganglion status $GANGLION_PROJECT\n```\n\n**Start in remote mode:**\n```bash\nganglion serve ./my-subnet --bot-id alpha --port 8899\nexport GANGLION_URL=http://127.0.0.1:8899\n```\n\nThe project directory must contain a `config.py` that defines `subnet_config` (SubnetConfig) and `pipeline` (PipelineDef). See `{baseDir}/references/configuration.md` for full config details.\n\n## Key Features\n\n### Observe State\nQuery the current framework state — registered tools, agents, pipeline definition, knowledge, metrics, and run history. Local mode uses CLI commands; remote mode uses GET endpoints.\n\nFull reference: `{baseDir}/references/commands.md`\n\n### Execute Pipelines\nRun the full pipeline or a single stage. The orchestrator executes stages in dependency order, applies retry policies, injects accumulated knowledge into agent prompts, and records outcomes.\n\n```bash\n# Local\nganglion run ./my-subnet\nganglion run ./my-subnet --stage plan\n\n# Remote\ncurl -s -X POST \"$GANGLION_URL/v1/run/pipeline\" -H \"Content-Type: application/json\" -d '{}' | jq .data\ncurl -s -X POST \"$GANGLION_URL/v1/run/stage/plan\" -H \"Content-Type: application/json\" -d '{}' | jq .data\n```\n\n### Mutate at Runtime (Remote Only)\nRegister new tools, agents, and components; patch the pipeline; swap retry policies; update prompts. All mutations are validated, audited, and reversible.\n\n```bash\n# Register a tool\ncurl -s -X POST \"$GANGLION_URL/v1/tools\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"my_tool\",\"code\":\"<code>\",\"category\":\"training\"}' | jq .data\n\n# Patch pipeline\ncurl -s -X PATCH \"$GANGLION_URL/v1/pipeline\" -H \"Content-Type: application/json\" \\\n  -d '{\"operations\":[{\"op\":\"add_stage\",\"stage\":{\"name\":\"validate\",\"agent\":\"Validator\",\"depends_on\":[\"train\"]}}]}' | jq .data\n```\n\nPipeline operations: `add_stage`, `remove_stage`, `update_stage`. See `{baseDir}/references/commands.md` for all mutation endpoints.\n\n### Knowledge Store\nCross-run strategic memory that compounds over time. Records patterns (what worked) and antipatterns (what failed), then automatically injects relevant history into agent prompts. Knowledge is queried by capability and filtered by bot_id for multi-bot setups.\n\n```bash\n# Local\nganglion knowledge ./my-subnet --bot-id alpha --capability training\n\n# Remote\ncurl -s \"$GANGLION_URL/v1/knowledge?capability=training&max_entries=10\" | jq\n```\n\n### Rollback\nUndo any mutation. Every mutation is recorded in an audit log with rollback data.\n\n```bash\ncurl -s -X POST \"$GANGLION_URL/v1/rollback/last\" | jq\ncurl -s -X POST \"$GANGLION_URL/v1/rollback/0\" | jq    # undo ALL mutations\n```\n\n### Multi-Bot Workflows\nMultiple OpenClaw sessions share a knowledge pool via `--bot-id`. Each bot's discoveries flow into the shared pool. Cooperation emerges from shared knowledge, not explicit coordination.\n\n```bash\n# Two local sessions\nganglion run ./my-subnet --bot-id alpha\nganglion run ./my-subnet --bot-id beta\n\n# Two remote servers\nganglion serve ./my-subnet --bot-id alpha --port 8899\nganglion serve ./my-subnet --bot-id beta  --port 8900\n```\n\n### MCP Integration\nConnect to external MCP servers to add tools to the agent's repertoire at runtime.\nTools from MCP servers appear as regular Ganglion tools with a prefix.\n\n```bash\n# Static: add to config.py\n# from ganglion.mcp.config import MCPClientConfig\n# mcp_clients = [MCPClientConfig(name=\"weather\", transport=\"stdio\", command=[\"python\", \"-m\", \"weather_server\"])]\n\n# Dynamic: add at runtime via API\ncurl -s -X POST \"$GANGLION_URL/v1/mcp/servers\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"weather\",\"transport\":\"stdio\",\"command\":[\"python\",\"-m\",\"weather_server\"]}' | jq .data\n\n# Check connected MCP servers\ncurl -s \"$GANGLION_URL/v1/mcp\" | jq .data\n\n# Disconnect\ncurl -s -X DELETE \"$GANGLION_URL/v1/mcp/servers/weather\" | jq .data\n\n# Expose Ganglion tools as MCP server (for Claude Desktop etc.)\nganglion mcp-serve ./my-subnet --transport stdio\n```\n\n## Common Workflows\n\nSee `{baseDir}/examples/common-workflows.md` for full step-by-step guides.\n\n1. **First run**: `ganglion init` → edit `config.py` → `ganglion run`\n2. **Iterative mining**: check status → review knowledge → run pipeline → check metrics → repeat\n3. **Dynamic mutation**: observe tools/agents → register new tool via API → patch pipeline → run\n4. **Multi-bot setup**: start multiple servers with different `--bot-id` values on the same project\n5. **MCP integration**: connect external tool servers → tools appear in registry → agents can use them\n\n## When Things Go Wrong\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| `FileNotFoundError: No config.py` | Wrong project path | Verify path contains `config.py` |\n| `OPENAI_API_KEY` errors | Missing or invalid API key | `export OPENAI_API_KEY=sk-...` |\n| `ConcurrentMutationError` | Mutating during a pipeline run | Wait for the run to finish |\n| `PipelineValidationError` | Invalid pipeline DAG (cycles, missing deps) | Check `ganglion pipeline` output |\n| Agent stuck / max turns reached | Agent cannot make progress | Review knowledge, swap retry policy, adjust prompts |\n\nFull troubleshooting: `{baseDir}/references/troubleshooting.md`\n\n## Retry Policies\n\nFour built-in policies control how stages retry on failure:\n- **NoRetry** — single attempt\n- **FixedRetry** — retry N times (default: 3)\n- **EscalatingRetry** — increase temperature per attempt, optional stall detection\n- **ModelEscalationRetry** — climb a model cost ladder (cheap → expensive)\n\nThree presets: `SN50_PRESET` (escalating + stall detection), `SIMPLE_PRESET` (fixed), `AGGRESSIVE_PRESET` (model escalation).\n\n## Additional Resources\n\n- Full CLI & API reference: `{baseDir}/references/commands.md`\n- Configuration guide: `{baseDir}/references/configuration.md`\n- Operational procedures: `{baseDir}/references/operations.md`\n- Troubleshooting: `{baseDir}/references/troubleshooting.md`\n- Workflow examples: `{baseDir}/examples/common-workflows.md`\n- Sample API requests: `{baseDir}/examples/sample-requests.md`\n- Health check script: `{baseDir}/scripts/healthcheck.sh`\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":755,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772616418311,"updatedAt":1778995141795},"latestVersion":{"version":"1.0.0","createdAt":1772616418311,"changelog":"Initial release of the codebase-guide skill for Ganglion operator workflows.\n\n- Provides comprehensive instructions for running Ganglion, including local and remote usage.\n- Documents CLI commands, HTTP bridge API, project scaffolding, configuration, and common workflows.\n- Explains knowledge store mechanics, runtime mutation, rollback features, and multi-bot workflows.\n- Details how to integrate MCP servers to extend agent toolkits at runtime.\n- Includes troubleshooting section for common operational issues.","license":null},"metadata":{"setup":[{"key":"OPENAI_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"tensorlink-dev","userId":"s1779k09srs2x10mha4aan1875884rwb","displayName":"tensorlink-dev","image":"https://avatars.githubusercontent.com/u/193437181?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089754401}}