agentic-ecos
Provides tools for ecosystem branch creation, syncing with upstream, and merging changes, ensuring traceable and version-controlled management of the ecosystem and its knowledge.
Facilitates private fork management, pull request workflows, and configuration of GitHub secrets, enabling secure collaboration and integration with GitHub-hosted repositories.
Includes GitHub Actions workflows for automated ecosystem snapshots, weekly summaries, pre-dev verification, knowledge review, and task automation, with optional LLM-powered synthesis and graceful degradation.
Generates Obsidian vaults as part of project initialization and provides tools like vault_query_graph to query the vault's knowledge graph for context-aware interactions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agentic-ecos Initialize agentic infrastructure for my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agentic-ecos
Control plane for traceable agentic infrastructure. agentic-ecos is an MCP
server that bootstraps, manages, and operates multi-agent coordination across
your entire digital ecosystem — not just one project.
It generates the full agentic stack in any project (locks, tasks with kanban, inter-agent communication, session audit, access control, protocol documents, and an Obsidian vault). It maintains a canonical registry of every project in your ecosystem and their agentic health. It encodes 15 battle-tested coordination patterns that agents query to avoid rediscovering the same solutions. And it handles the complete task lifecycle — create, claim, work, complete — with git-based traceability that records who did what and when.
All of this works local-first: agents coordinate via git push rejection, no central server required. GitHub Actions and LLM-synthesized automation are available as an optional layer on top.
Python 3.10+ · git · 37 MCP tools · 85 tests · MIT
Compatible with any MCP client: OpenCode, Claude Code, Cursor, and others
LLM-agnostic automation: DeepSeek, GPT, Claude, Ollama — opt-in
Vault autodocumental abrible en Obsidian (
docs/)
# Fork con nombre propio (universal: funciona para dueño y terceros)
gh repo fork deibanez/agentic-ecos --clone --fork-name agentic-ecos-priv
gh repo edit --visibility private # settings → danger zone → change visibility
cd agentic-ecos-priv && uv add --dev mcp && uv pip install --editable .
agentic-ecos connect --agent auto # sin --target: usa workspace_root de agentic.toml o CWDWhy
You get | Instead of | So you can |
Multi-agent coordination via git | Central servers, lock services | Any agent, any machine, no extra infra |
Task lifecycle with T-ID traceability | Ad-hoc bash + manual git | Know who did what and when |
15 battle-tested agentic patterns | Rediscovering coordination every project | Reuse proven logic |
Automated project bootstrapping | Manual setup of locks/tasks/comms | 42 files generated in seconds |
LLM-agnostic automation (opt-in) | Vendor lock-in | Choose your provider freely |
Related MCP server: orchestrator-mcp
Requirements
Requisito | Mínimo | Nota |
Python | 3.10+ | Compatible con 3.11, 3.12 |
git | Cualquiera reciente | Coordinación agéntica (git push rejection) |
gh CLI | 2.0+ |
|
Instalador |
|
|
Cliente MCP | Cualquiera | OpenCode, Claude Code, Cursor, etc. — agnóstico |
LLM (opcional) | Ninguno | Solo para automatización con síntesis de IA ( |
Instalación de herramientas base (una vez por máquina):
# git (Linux: apt/snap · macOS: brew)
sudo apt install git # o: brew install git
# gh CLI (GitHub CLI)
sudo apt install gh # o: brew install gh
gh auth login # autenticarse (usar HTTPS o SSH)
# uv (gestor de paquetes Python)
pip install uv # o: curl -LsSf https://astral.sh/uv/install.sh | shQuickstart
Setup único — fork privado + instalación
El fork privado cubre ambos casos de uso: las tools del Modo 1 (simple)
funcionan igual en un fork, y habilita el Modo 2 (ecosistema) cuando lo
necesites. Solo main y dev del upstream son públicos — tu ecosistema vive
en el fork privado (trazabilidad completa con git log).
# 0. Fork privado + upstream (una vez) — universal, funciona para dueño y terceros
gh repo fork deibanez/agentic-ecos --clone --fork-name agentic-ecos-priv
gh repo edit --visibility private
cd agentic-ecos-priv
git remote add upstream https://github.com/deibanez/agentic-ecos.git
# 1. Dependencias + CLI (una vez)
uv add --dev mcp
uv pip install --editable .
# 2. Branch de ecosistema (una vez) — trazable, registra en AGENT_SESSION_LOG
agentic-ecos ecosystem branch-create mi-eco --base main
# base=main (estable, recomendado) | base=dev (bleeding edge)
# 3. Plano de control (una vez por ecosistema)
agentic-ecos ecosystem init --name mi-ecosistema --workspace ~/repos
# --workspace = dónde viven tus proyectos (ajustá a tu ruta)
# 4. Conectar el MCP a tu agente (una vez por workspace)
agentic-ecos connect --agent auto
# Sin --target: usa el workspace_root definido por ecosystem_init (paso 3),
# así que escribe opencode.jsonc en la raíz de tu workspace, no en el repo.
# Solo usa --target explícito si querés escribir en otro directorio.
# 5. Verificar
agentic-ecos protocolsUso inmediato (Modo 1 — sin registro de proyectos)
Las tools MCP funcionan inmediatamente tras conectar el server:
# Desde tu agente (con el MCP conectado):
# init_project("mi-proyecto", preset="monorepo", target_path=".../docs")
# list_patterns() → los 15 patrones agénticos
# validate_structure("...") → verifica cobertura agéntica
# protocol_template("agent_protocol") → plantilla de protocoloHow tasks work
Tasks are local-first: they run in your agent session using git for coordination. No central server, no CI/CD required.
flowchart LR
add[ecosystem_task_add] --> backlog[(backlog)]
backlog --> claim[ecosystem_task_claim]
claim --> doing[(doing)]
doing --> done[ecosystem_task_done]
done --> log[(AGENT_SESSION_LOG.md)]Race-free claiming: claim does git commit + git push. If two agents
claim the same task, the second push is rejected — the agent picks another.
Every action is traced with a T-ID.
agentic-ecos ecosystem add-task "Fix staging deploy" --priority high --type ci-cd
agentic-ecos ecosystem task-status --filter unclaimed
agentic-ecos ecosystem claim E1 --agent opencode-nesto
# ... work: changes → verify → commit [agent:: opencode-nesto] ...
agentic-ecos ecosystem done E1 --agent opencode-nestoGitHub Actions is optional: task-automation.yml automates the same cycle
for docs/ops tasks. Not needed for daily agent work — see
CONTRIBUTING.md §9.
Key design
Feature | What it does |
Auto-context on connect | The agent receives instructions in the MCP handshake — no need to memorize the 37 tools. |
Live context in every response | Every MCP tool response carries |
Local-first task lifecycle | Add/claim/done with race-free git push rejection. Every action traced with a T-ID |
4-tier knowledge | Patterns grow: personal → ecosystem → community → built-in |
LLM-agnostic | DeepSeek, GPT, Claude, Ollama — any provider. Works without LLM too (graceful degradation) |
Multi-agent MCP | OpenCode, Claude Code, Cursor — one command: |
Core tools
Category | Tools |
Projects |
|
Ecosystem |
|
Tasks |
|
Knowledge |
|
Git Ops |
|
Full reference: ARCHITECTURE.md §7 documents all 37 tools.
Knowledge lifecycle
flowchart TB
D[discover] --> T3[(data/ tier 3)]
T3 --> V{validated<br/>2+ projects?}
V -->|no| T3
V -->|yes| T25[(workspace/ tier 2.5)]
T25 --> S{shared with<br/>community?}
S -->|no| T25
S -->|yes| T2[(knowledge/ tier 2)]
T2 --> M{mature<br/>enough?}
M -->|no| T2
M -->|yes| T1[(patterns.py tier 1)]Tier | Location | Git | Cycle |
3 · Personal |
| ✓ committed (private fork) |
|
2.5 · Ecosystem |
| ✓ (tu branch) |
|
2 · Community |
| ✓ committed |
|
1 · Built-in |
| ✓ committed | Move to code → everyone |
Solo el runtime data (data/ecosystem-snapshots/, data/state.json) queda
gitignored — no es conocimiento y genera conflictos de merge.
LLM Automation (opt-in)
Set these secrets to unlock AI-synthesized weekly summaries, task proposals, PR reviews and automated task loops:
Secret | Required | Description |
| ✓ | API key del provider |
| ⏸️ | Default |
| ⏸️ | Solo para providers custom |
Degradación elegante: sin LLM_API_KEY, los workflows commitean los datos
crudos sin síntesis. El sistema nunca falla por LLM no configurado.
See CONTRIBUTING.md §9 for the full CI/CD setup.
CLI reference
# Projects
agentic-ecos init mi-proyecto --preset monorepo --repos api,frontend
agentic-ecos validate ./ruta/al/vault
# Ecosystem
agentic-ecos ecosystem init --name eco --workspace ~/repos
agentic-ecos ecosystem status
agentic-ecos ecosystem add otro-svc --type frontend
# Tasks (local-first)
agentic-ecos ecosystem add-task "Migrar satet" --priority high --type iac
agentic-ecos ecosystem claim E1 --agent opencode-alpha
agentic-ecos ecosystem done E1 --agent opencode-alpha
agentic-ecos ecosystem task-status --filter unclaimed
# Git ops (traceable)
agentic-ecos ecosystem branch-create mi-eco --base main
agentic-ecos ecosystem sync --branch main
agentic-ecos ecosystem merge-main --target ecosystem/mi-eco
# Knowledge
agentic-ecos promote mi-pattern --to workspace
agentic-ecos promote mi-pattern --to knowledge --source workspace
agentic-ecos knowledge status
# Automation (JSON output for CI)
agentic-ecos ecosystem status --json
agentic-ecos llm-test --prompt "Hola"Presets
monorepo— múltiples servicios con CI/CD compartido e IaC centralizadasingle_service— un servicio con componentes en subdirectoriosdata_pipeline— lambdas, jobs batch, pipeline de ingesta/procesamiento
Structure
agentic_ecos/
├── server.py # MCP server (37 tools)
├── generator.py # init_project + generate_file + validate + CLI
├── patterns.py # 15 patrones agénticos (tier 1)
├── protocols.py # 5 plantillas de protocolos
├── presets.py # monorepo / single_service / data_pipeline
├── ecosystem.py # plano de control (agentic.toml, connect, tasks)
├── storage.py # data/ + knowledge/ + workspace/ carga/guardado
├── knowledge.py # promoción entre tiers
├── llm.py # motor de síntesis LLM agnóstico
├── task_loop.py # desarrollo continuo (detect→claim→plan→execute→verify)
├── knowledge/ # tier 2 · comunidad
├── data/ # tier 3 · personal (snapshots/state gitignored)
├── static/ # scripts copiados tal cual a cada proyecto
└── templates/ # plantillas markdown generables
.github/workflows/ # 5 workflows de automatización
workspace/ # tier 2.5 · solo en branches de ecosistema
docs/00_Global/ # vault autodocumental (Obsidian)Docs
ARCHITECTURE.md — capas, patrones, plano de control, pipeline de generación
CONTRIBUTING.md — uso, forking, ciclo del conocimiento, privacidad, CI/CD
instructions.md — prompt del agente
LICENSE — MIT License
Roadmap
Task loop scheduling (actualmente solo
workflow_dispatch)RAG opt-in para vaults grandes
Available Tools
37 toolsadd_custom_patternA
Agrega un patrón agéntico descubierto por un agente a data/patterns-custom.json (disponible para todos los proyectos; promocionar a patterns.py cuando madure).
Inputs: pattern (required).
add_custom_presetB
Agrega un preset custom a data/presets-custom.json.
Inputs: name (required), preset (required).
agentic_healthC
Reporte de salud agéntica de un proyecto (coverage + gaps + sugerencias).
Inputs: project_path (required).
connectB
Configura agentic-ecos como MCP server para uno o más agentes (opencode, claude, cursor, auto, snippet). No modifica configs existentes de otros servers.
Inputs: agent, target, config_path, agentic_path, +1 more.
connect_statusC
Detecta qué agentes tienen config en target y si agentic-ecos está conectado.
Inputs: target, config_path.
ecosystem_branch_createA
Crea la branch ecosystem/{name} desde base (default: main). Trazable: registra la operación en AGENT_SESSION_LOG.
Inputs: name (required), base.
ecosystem_configC
Devuelve el registro agentic.toml completo (proyectos + defaults).
Inputs: config_path.
ecosystem_initB
Inicializa el plano de control: crea agentic.toml en el workspace con registro canónico de proyectos y sus defaults.
Inputs: workspace_root (required), name, scan, ci_cd, +5 more.
ecosystem_merge_mainA
Mergea main a la branch de ecosistema (target_branch o branch actual). Reporta archivos en conflicto si los hay.
Inputs: target_branch.
ecosystem_statusC
Reporte de salud del ecosistema completo: proyectos, cobertura agéntica, gaps.
Inputs: config_path.
ecosystem_sync_upstreamA
Sincroniza una branch local con upstream (git fetch + merge). branch='main' actualiza estable; branch='dev' actualiza bleeding edge.
Inputs: branch.
ecosystem_task_addC
Agrega una tarea cross-cutting al workspace/tasks.md (commiteable en tu branch).
Inputs: description (required), type, scope, priority, +1 more.
ecosystem_task_claimA
Reclama una tarea: agrega [agent::] + [status:: doing] + commit + push. Race-free con git push rejection (si otro agente reclamó primero, falla). Trazable con T-ID.
Inputs: task_id (required), agent_id (required), tasks_file.
ecosystem_task_doneA
Marca una tarea como completada: [status:: done] + commit + push. Verifica que el agent_id que completa es el que la reclamó.
Inputs: task_id (required), agent_id (required), tasks_file.
ecosystem_tasksC
Agregado de tareas del ecosistema: cross-cutting (workspace/tasks.md) + conteo por proyecto.
Inputs: config_path.
ecosystem_task_statusB
Consulta el estado de tareas: por ID, o filtradas por agente/estado (unclaimed | claimed | done | backlog | agent-id).
Inputs: task_id, tasks_file, filter_agent.
generate_fileC
Genera un archivo individual desde un template.
Inputs: file_name (required), target_path (required), context.
get_patternC
Devuelve un patrón agéntico específico con guía de implementación.
Inputs: name (required).
init_projectB
Genera el esqueleto completo de infraestructura agéntica en un proyecto (locks, tasks, comms, session audit, protocols, vault, MCP skeleton).
Inputs: project_name (required), ci_cd, cloud, repos, +4 more.
knowledge_statusA
Reporta el estado del conocimiento por tier (built-in / knowledge / workspace / custom).
Inputs: no named parameters.
list_patternsA
Lista los patrones agénticos disponibles, opcionalmente por dominio.
Inputs: domain.
list_presetsA
Lista los presets de tipos de proyecto disponibles.
Inputs: no named parameters.
list_protocolsA
Lista las plantillas de protocolos disponibles.
Inputs: no named parameters.
project_addC
Registra un proyecto en agentic.toml (detecta si ya tiene infra agéntica).
Inputs: name (required), path, type, notes, +3 more.
project_removeA
Elimina un proyecto del registro agentic.toml.
Inputs: name (required), config_path.
promote_to_knowledgeA
Copia un pattern de workspace/ o data/ a knowledge/ (commiteable, para PR a upstream).
Inputs: name (required), kind, source.
promote_to_workspaceA
Mueve un pattern de data/ (personal) a workspace/patterns/ (commiteable en tu branch de ecosistema).
Inputs: name (required), config_path.
protocol_templateB
Devuelve una plantilla de protocolo con placeholders reemplazados.
Inputs: name (required), context.
rag_statusB
Verifica si el vault del proyecto está indexado para RAG (opt-in).
Inputs: target_path.
remove_custom_patternB
Elimina un patrón custom de data/patterns-custom.json.
Inputs: name (required).
remove_custom_presetB
Elimina un preset custom de data/presets-custom.json.
Inputs: name (required).
save_snapshotB
Guarda un snapshot histórico (ej: de ecosystem_status) en data/ecosystem-snapshots/.
Inputs: label, payload.
scan_opencodeC
Escanea el workspace y reporta qué proyectos tienen agentic-ecos conectado.
Inputs: workspace_root.
set_stateB
Guarda una clave/valor en el estado interno del MCP (data/state.json).
Inputs: key (required), value.
storage_statusA
Reporta el estado del almacenamiento orgánico (data/): custom patterns/presets, snapshots, state.
Inputs: no named parameters.
suggest_next_stepsC
Sugiere próximos pasos priorizados para un proyecto.
Inputs: project_path (required).
validate_structureC
Valida qué piezas de infraestructura agéntica existen en un proyecto.
Inputs: project_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Most tools have distinct purposes, but there is some overlap between ecosystem_tasks and ecosystem_task_status, as both deal with task overview/state. Additionally, add_custom_pattern, promote_to_workspace, and promote_to_knowledge all involve adding patterns to different locations, though the contexts are clear.
All tool names use snake_case and mostly follow a verb_noun pattern (e.g., list_patterns, add_custom_preset, remove_custom_pattern). However, there are some deviations like 'connect' (bare verb) and 'rag_status' (noun_noun), and a mix of prefixes (ecosystem_, project_, agentic_) that slightly reduces consistency.
With 37 tools, the server exceeds the threshold for 'too many' (25+). The tool set could be consolidated, such as grouping git operations (ecosystem_branch_create, ecosystem_sync_upstream, ecosystem_merge_main) or task operations (add/claim/done/status) into fewer tools with parameters.
The tool surface covers the core workflows of the agentic ecosystem domain: project initialization, validation, health reporting, pattern/protocol/preset management, agent connections, task management, git operations, and knowledge tiers. Minor gaps exist, such as no update/delete for tasks and no update for custom patterns, but these are workable.
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP-first control plane for ProAgentStore agents and private instances.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Hosted AgentLux MCP server for marketplace, identity, creator, services, and social flows.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for cross-platform agent onboarding. Registers external agents, translates intents from LangChain, CrewAI, AutoGen, and A2A formats, and proxies cross-ecosystem transactions.MIT
- FlicenseNot gradedqualityDmaintenanceMulti-model agent orchestration MCP server that enables plan-code-review-deliver pipelines with configurable providers and models.-
- AlicenseNot gradedqualityBmaintenanceMCP server for agentic task orchestration and management, enabling AI agents to create goals, plan tasks with acceptance criteria, track dependencies, request human input, and provide proof of completion.27 npm3MIT
- FlicenseAqualityCmaintenanceAn MCP server that exposes governance, trust-scoring, compliance, guardrail, cost, drift, and supply-chain scanning tools and resources to any MCP client over stdio, Streamable HTTP, or legacy HTTP+SSE. It lets agents route every tool call through a deterministic five-way decision (allow, redact, require approval, deny, or quarantine) with hash-chained evidence, human approval workflows, and in-agent trust gates for LangChain, LangGraph, and Google ADK.30-