Skip to main content
Glama

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 CWD

Why

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+

gh auth login para forkear y gestionar visibilidad

Instalador

uv (recomendado) o pip

pip install uv · uv add --dev mcp

Cliente MCP

Cualquiera

OpenCode, Claude Code, Cursor, etc. — agnóstico

LLM (opcional)

Ninguno

Solo para automatización con síntesis de IA (LLM_API_KEY)

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 | sh

Quickstart

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 protocols

Uso 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 protocolo

How 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-nesto

GitHub 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. connect also adds instructions.md to the workspace config

Live context in every response

Every MCP tool response carries _context with ecosystem summary, task backlog and knowledge state — the agent always has the current pulse without extra calls

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: connect --agent auto

Core tools

Category

Tools

Projects

init_project, validate_structure, agentic_health

Ecosystem

ecosystem_init, ecosystem_status, ecosystem_tasks

Tasks

ecosystem_task_add, ecosystem_task_claim, ecosystem_task_done, ecosystem_task_status

Knowledge

list_patterns, add_custom_pattern, promote_to_knowledge, knowledge_status

Git Ops

ecosystem_branch_create, ecosystem_sync_upstream, ecosystem_merge_main, connect

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

agentic_ecos/data/ (patterns/presets)

✓ committed (private fork)

add_custom_pattern → experiment

2.5 · Ecosystem

workspace/

✓ (tu branch)

promote_to_workspace → validated

2 · Community

agentic_ecos/knowledge/

✓ committed

promote_to_knowledge → PR to main

1 · Built-in

agentic_ecos/patterns.py

✓ 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

LLM_API_KEY

✓

API key del provider

LLM_MODEL

⏸️

Default deepseek-chat. Ej: gpt-4o, claude-3-5-sonnet

LLM_BASE_URL

⏸️

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 centralizada

  • single_service — un servicio con componentes en subdirectorios

  • data_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

Roadmap

  • Task loop scheduling (actualmente solo workflow_dispatch)

  • RAG opt-in para vaults grandes

Available Tools

37 tools
add_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

    B3.1/5.0

    Scored across 37 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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 npm
      3
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      An 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
      -