{"id":49411789,"url":"https://github.com/canoo/agent-nexus","last_synced_at":"2026-04-29T01:01:21.331Z","repository":{"id":353280333,"uuid":"1207249136","full_name":"canoo/agent-nexus","owner":"canoo","description":"Multi-model agentic orchestration framework — route tasks to cloud or local LLMs, manage personas, and configure everything through an interactive TUI.","archived":false,"fork":false,"pushed_at":"2026-04-23T08:37:53.000Z","size":1360,"stargazers_count":3,"open_issues_count":17,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T09:06:45.747Z","etag":null,"topics":["agent","ai","bubbletea","cli","go","llm","mcp","multi-model","ollama","orchestration","tui"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/canoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-10T18:29:53.000Z","updated_at":"2026-04-23T08:47:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/canoo/agent-nexus","commit_stats":null,"previous_names":["canoo/agent-nexus"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/canoo/agent-nexus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canoo%2Fagent-nexus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canoo%2Fagent-nexus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canoo%2Fagent-nexus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canoo%2Fagent-nexus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canoo","download_url":"https://codeload.github.com/canoo/agent-nexus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canoo%2Fagent-nexus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32405903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: 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":["agent","ai","bubbletea","cli","go","llm","mcp","multi-model","ollama","orchestration","tui"],"created_at":"2026-04-29T01:00:54.814Z","updated_at":"2026-04-29T01:01:21.306Z","avatar_url":"https://github.com/canoo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NEXUS\n\n[![Release](https://img.shields.io/github/v/release/canoo/agent-nexus?style=flat-square)](https://github.com/canoo/agent-nexus/releases)\n[![CI](https://img.shields.io/github/actions/workflow/status/canoo/agent-nexus/ci.yml?branch=main\u0026style=flat-square\u0026label=CI)](https://github.com/canoo/agent-nexus/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square\u0026logo=go\u0026logoColor=white)](https://go.dev)\n[![Linux](https://img.shields.io/badge/Linux-supported-FCC624?style=flat-square\u0026logo=linux\u0026logoColor=black)](https://github.com/canoo/agent-nexus)\n[![macOS](https://img.shields.io/badge/macOS-supported-000000?style=flat-square\u0026logo=apple\u0026logoColor=white)](https://github.com/canoo/agent-nexus)\n[![CodeRabbit Reviews](https://img.shields.io/coderabbit/prs/github/canoo/agent-nexus?style=flat-square\u0026labelColor=171717\u0026color=FF570A\u0026label=CodeRabbit+Reviews)](https://coderabbit.ai)\n\n**Network of EXperts, Unified in Strategy**\n\nRoute boilerplate to local models. Save cloud credits for what matters. One config, every AI tool.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo.gif\" alt=\"NEXUS TUI Demo\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/canoo/agent-nexus/main/install.sh | bash\nnexus\n```\n\n\u003e Make sure `~/.local/bin` is in your `PATH`: `export PATH=\"$HOME/.local/bin:$PATH\"`\n\n---\n\n## The Problem\n\nEvery AI coding tool speaks its own configuration dialect. Switching tools — or using more than one — means manually maintaining separate instruction files for each:\n\n| Tool | Config file |\n|---|---|\n| Claude Code | `CLAUDE.md`, `AGENTS.md` |\n| Cursor | `.cursor/rules/*.mdc` |\n| Windsurf | `.windsurfrules` |\n| Copilot | `.github/copilot-instructions.md` |\n| Kiro | `.kiro/steering/*.md` |\n| Cline | `.clinerules` |\n| Continue.dev | `.continuerc.json` / `config.yaml` |\n| Amazon Q | `.qrules` |\n\nDevelopers describe this as \"copy-pasting their soul from one tool's rule file to another.\" When a team member switches tools or a new one launches, all of that context has to be manually migrated — and the project memory trapped in one tool's scratchpad is lost entirely.\u003csup\u003e[1]\u003c/sup\u003e\n\nOn top of that, every tool has its own MCP server config location. Adding a single MCP server means editing JSON in three or four different places.\n\n**NEXUS is the layer underneath all of them.** Define your project instructions, personas, and routing rules once. NEXUS projects them into each tool's native format, routes appropriate tasks to local models to reduce cloud spend, and preserves context across sessions and tool switches.\n\n---\n\n## What NEXUS Does Today\n\n### 1. Complexity-based local routing (zero-token git)\n\nNEXUS routes micro-tasks to local Ollama models based on complexity, reserving cloud API tokens for work that actually needs them. The most concrete example: commit messages, lint fixes, and boilerplate generation routed to a local 1.5B model instead of Sonnet.\n\nDevelopers routing these tasks locally report saving thousands of cloud tokens per day.\u003csup\u003e[2]\u003c/sup\u003e\n\n```\nTask: generate commit message from diff\n→ Local:  qwen2.5-coder:1.5b  (~143 t/s, $0.00)\n→ Cloud:  claude-sonnet        (~70 t/s, $0.003/req)\n```\n\nThis matters more as AI Credits pricing shifts toward token-based billing across major providers.\n\n### 2. Specialist persona system\n\nNEXUS ships a library of specialist agent personas — engineering roles with defined responsibilities, tooling knowledge, and escalation behaviour. The orchestrator delegates to the right specialist rather than doing everything in one context.\n\nPersonas live in `~/.config/nexus/personas/` as markdown files. The active persona set is projected into every configured tool automatically.\n\n### 3. Unified config projection\n\nSteering files, personas, and routing rules are maintained in one place and projected into each installed AI tool's native format via symlinks and generated files. When you update a persona or routing rule, `nexus sync` propagates it everywhere.\n\n### 4. MCP server for local model delegation\n\nThe `nexus-ollama` MCP server exposes local Ollama delegation as standard MCP tools. Any MCP-capable tool (Claude Code, Cursor, Windsurf, Cline, Continue.dev, Kiro) can route tasks locally without custom integration.\n\n```json\n{\n  \"mcpServers\": {\n    \"nexus-ollama\": {\n      \"command\": \"node\",\n      \"args\": [\"~/.config/nexus/tools/mcp/server.mjs\"]\n    }\n  }\n}\n```\n\nAvailable tools: `ollama_commit_msg`, `ollama_boilerplate`, `ollama_test_scaffold`, `ollama_lint_fix`, `ollama_logic_refactor`.\n\n### 5. TUI for setup and health\n\nAn interactive terminal UI handles installation, configuration, health checks, and updates. No config file editing required to get started.\n\n---\n\n## Tool Compatibility\n\n| Tool | Config format | MCP support | NEXUS status |\n|---|---|---|---|\n| Claude Code | `AGENTS.md`, `CLAUDE.md` | ✓ | ✅ Full |\n| Gemini CLI | `AGENTS.md` | ✓ | ✅ Full |\n| Kiro | `.kiro/steering/*.md` | ✓ | ✅ Full |\n| Cursor | `.cursor/rules/*.mdc` | ✓ | 🔄 Planned — v0.2.5 |\n| Copilot | `.github/copilot-instructions.md` | GitHub-managed | 🔄 Planned — v0.2.5 |\n| Windsurf | `.windsurfrules` | ✓ | 🔄 Planned — v0.2.5 |\n| Cline | `.clinerules` | VS Code shared | 🔄 Planned — v0.2.5 |\n| Continue.dev | `.continuerc.json` | ✓ | 🔄 Planned — v0.2.5 |\n| Amazon Q | `.qrules` | ✓ | 📋 Backlog |\n| Crush | Agent Skills | ✓ | 📋 Backlog |\n| Aider | `.aider.conf.yml` | — | 📋 Backlog |\n| Zed | `.zed/settings.json` | ✓ | 📋 Backlog |\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n    classDef user fill:#6c5ce7,stroke:#333,stroke-width:2px,color:#fff;\n    classDef nexus fill:#00b894,stroke:#333,stroke-width:2px,color:#fff;\n    classDef tool fill:#a29bfe,stroke:#333,stroke-width:2px,color:#fff;\n    classDef mcp fill:#00cec9,stroke:#333,stroke-width:2px,color:#fff;\n    classDef local fill:#d63031,stroke:#333,stroke-width:2px,color:#fff;\n    classDef cloud fill:#fdcb6e,stroke:#333,stroke-width:2px,color:#000;\n\n    U[Developer]:::user --\u003e N(NEXUS):::nexus\n\n    N --\u003e|projects config to| CC[Claude Code]:::tool\n    N --\u003e|projects config to| GC[Gemini CLI]:::tool\n    N --\u003e|projects config to| KC[Kiro]:::tool\n    N --\u003e|projects config to| CU[Cursor · Windsurf · Cline]:::tool\n\n    CC --\u003e O(nexus-ollama MCP):::mcp\n    GC --\u003e O\n    KC --\u003e O\n    CU --\u003e O\n\n    O --\u003e|supervisor band 0.5–1.5B| L[Local Ollama]:::local\n    O --\u003e|logic band 2–3B| L\n\n    CC --\u003e|deep work| CL[Cloud APIs]:::cloud\n    GC --\u003e|deep work| CL\n```\n\n---\n\n## Local Model Configuration\n\nNEXUS defaults to `http://localhost:11434`. To use a dedicated GPU server, configure via the TUI or edit `.env` directly.\n\n### Routing bands\n\n| Band | Models | Tasks | Hardware |\n|---|---|---|---|\n| Supervisor | `qwen2.5-coder:1.5b` | Commit messages, JSON gen, boilerplate | 4 GB VRAM — \u003e120 t/s |\n| Logic | `llama3.2:3b` | Code generation, refactoring, lint fixes | 4 GB VRAM — ~75 t/s |\n| Logic+ | `qwen2.5-coder:7b` | Complex refactors, multi-file edits | 8 GB VRAM |\n| Heavy | `qwen2.5-coder:32b` | Architecture-level generation | 16 GB+ VRAM |\n\nThe supervisor and logic bands are the defaults. Override any route via environment variable:\n\n```bash\nNEXUS_SUPERVISOR_MODEL=qwen2.5-coder:1.5b\nNEXUS_LOGIC_MODEL=llama3.2:3b\nNEXUS_MODEL_COMMIT_MSG=qwen2.5-coder:1.5b   # per-task override\n```\n\nSee [docs/model-configuration.md](docs/model-configuration.md) for hardware-specific presets (RTX 3060–5090, MacBook M3/M3 Max, multi-GPU).\n\n---\n\n## TUI\n\n```\n⚡ NEXUS Framework Manager\n   v0.1.5\n\n▸ Install NEXUS\n  Configure\n  Health Check\n  Update\n  Uninstall NEXUS\n\nj/k: navigate • enter: select • q: quit\n```\n\n| Screen | What it does |\n|---|---|\n| **Install** | Step-by-step wizard: validates repo, creates symlinks, configures MCP, checks deps, pulls Ollama models |\n| **Configure** | Edit Ollama host URL and model overrides inline |\n| **Health Check** | Verifies Ollama reachability, symlink integrity, MCP server status |\n| **Update** | Checks latest release and self-updates with checksum verification |\n| **Uninstall** | Removes all symlinks and binary with confirmation |\n\n---\n\n## Installation\n\n### One-liner\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/canoo/agent-nexus/main/install.sh | bash\n```\n\nDownloads the pre-built `nexus` binary and clones the repo to `~/.config/nexus/repo`.\n\n### From source\n\n```bash\ngit clone https://github.com/canoo/agent-nexus.git\ncd agent-nexus\nbash setup-nexus.sh\n```\n\nRequires Go 1.25+ to build the TUI binary.\n\n---\n\n## Project Structure\n\n```\ncore/           Orchestrator instructions (NEXUS.md, AGENTS.md, kiro steering)\npersonas/       Specialist agent definitions\ntools/tui/      NEXUS TUI (Go / Bubbletea v2)\ntools/mcp/      nexus-ollama MCP server (Node.js)\ntools/compat/   Tool driver registry (tools.json) — planned v0.2.5\nprompts/        Engineering rules and quality gates\nmcp-configs/    MCP configuration templates\ndocs/           Documentation and hardware presets\ntests/          Integration tests\n```\n\n---\n\n## Roadmap\n\n| Version | Theme | Key deliverables |\n|---|---|---|\n| **v0.1.6** | Security fixes | Checksum hardening, input validation, PAT removal — [in progress] |\n| **v0.2.0** | Observability core | Session logging, cost tracker, live TUI dashboard |\n| **v0.2.1** | CLI usage ingestion | Tokscale adapter, unified usage dashboard |\n| **v0.2.5** | Universal sync layer | `nexus adopt`, `nexus sync`, AGENTS.md projection, tool driver system, nexus-context MCP, Smithery MCP registry, compatibility matrix |\n| **v0.3.0** | Dynamic routing | Auto model selection by task complexity, latency fallback, chain-of-models |\n| **v0.3.5** | Community benchmarks | Benchmark schema, hardware-tiered test runner, community submission pipeline, results showcase |\n| **v0.4.0** | Persona marketplace | Community persona sharing, persona composition, auto-update |\n| **v1.0.0** | Stable | Windows/Docker support, team features, stable public API |\n\n---\n\n## Prerequisites\n\n**Required:** Bash, one or more supported AI tools (see [compatibility table](#tool-compatibility))\n\n**Optional:** [Node.js](https://nodejs.org/) ≥18 (for MCP server), [Ollama](https://ollama.com/) (for local model delegation)\n\n\u003e **Platform support:** Linux and macOS. Windows support is tracked in [#18](https://github.com/canoo/agent-nexus/issues/18).\n\n\u003e No Go toolchain needed — the `nexus` binary is a pre-built download.\n\n---\n\n## Testing\n\n```bash\n# Go unit tests\ncd tools/tui \u0026\u0026 go test ./...\n\n# Full install/uninstall cycle (isolated temp $HOME)\nbash tests/test-install-cycle.sh\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR guidelines, and commit conventions.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n---\n\n## Research and Sources\n\nNEXUS's design is informed by documented developer pain points in the AI coding tool ecosystem:\n\n\u003csup\u003e[1]\u003c/sup\u003e Configuration wall and context leakage: r/ChatGPTCoding, r/LocalLLaMA, r/ClaudeCode — April 2026. Developers describe manually syncing `.cursor/rules/*.mdc`, `CLAUDE.md`, and `.github/copilot-instructions.md` as \"copy-pasting their soul\" between tools.\n\n\u003csup\u003e[2]\u003c/sup\u003e Zero-token git workflow: r/ClaudeCode — April 2026. Teams routing commit messages and boilerplate generation to local Ollama (`qwen2.5-coder:1.5b`) report saving thousands of cloud tokens per day.\n\nAdditional references: [Smithery MCP registry](https://smithery.ai) · [Official MCP registry](https://registry.modelcontextprotocol.io) · [Model Context Protocol](https://modelcontextprotocol.io)\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 [Codelogiic](https://www.codelogiic.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanoo%2Fagent-nexus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanoo%2Fagent-nexus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanoo%2Fagent-nexus/lists"}