convez.ai
MCP ServerAutomaçãoIntermediário
naxe-run

Naxe - Motor de Grafo de Tarefas com Dependências

naxe-run/naxe

Motor de grafo de tarefas que expõe apenas o que é acionável agora

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que funciona como um motor de grafo de tarefas ciente de dependências para agentes de IA. Em vez de deixar o agente raciocinar sobre o que é possível fazer, Naxe expõe apenas as tarefas que podem ser executadas no momento, simplificando a orquestração de workflows complexos. Suporta SQLite para uso local ou PostgreSQL para ambientes multi-agente.

Instalação

$npx convez-ai naxe-run/naxe

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
37%
Último commit
há 3 meses
Versão
v0.4.5
Issues abertas
0
Contribuidores
2

Casos de uso

  • Orquestração de workflows multi-etapas com dependências para agentes Claude
  • Rastreamento de refatorações e projetos de engenharia com múltiplas etapas
  • Coordenação de múltiplos agentes IA acessando o mesmo grafo de tarefas
  • Planejamento e execução incrementais onde cada passo é validado antes de ser oferecido

Veredito

Ferramenta bem pensada que resolve um problema real: agentes não precisam decidir o que *podem* fazer, apenas o que *devem* fazer. Implementação sólida com suporte a múltiplos bancos de dados e autenticação opcional; ideal para workflows determinísticos que requerem rastreamento de estado.

README

A tradução para o português deste README ainda está na fila.

Naxe

A local-first MCP server that acts as a dependency-aware task graph engine for AI agents. Agents write tasks with dependencies; the engine surfaces only the tasks that are actionable right now.

Core insight: agents shouldn't have to reason about what they can do — only what they should do.

Install

uv tool install naxe
# or: pipx install naxe
# or: pip install naxe

This makes the naxe command available globally.

For development (editable install):

git clone https://github.com/naxe-run/naxe
uv tool install --editable ./naxe

Quick Start

1. Run the setup wizard

naxe init

This walks you through database selection (SQLite or PostgreSQL), tests the connection, optionally registers an agent, and prints the exact claude mcp add command to paste into your shell.

Or configure manually (after uv tool install):

claude mcp add --scope user --transport stdio naxe \
  --env NAXE_DB_URL=postgresql://user:pass@localhost/naxe \
  --env NAXE_API_KEY=naxe_sk_... \
  -- naxe

Omit --env NAXE_API_KEY if running in open mode (no registered agents). --scope user makes the MCP available in all your projects.

2. Start using it

In a Claude Code session, ask Claude to use Naxe for multi-step tasks:

"Use Naxe to track this refactor. Create a job with tasks for each step."

Claude will call create_job and add_tasks to plan the work, then work through tasks using claim_task and complete_task.

Database

Naxe supports two backends:

SQLite (default — zero setup)

A naxe.db file is created in the working directory automatically. Good for personal use and ephemeral agent sessions.

# Override the path
export NAXE_DB_PATH=/path/to/my.db
# Or use a full URL
export NAXE_DB_URL=./naxe.db

PostgreSQL (recommended for multi-agent or shared use)

Install the PostgreSQL extra:

Then point naxe at your database:

export NAXE_DB_URL=postgresql://user:pass@localhost/naxe

Or store it permanently:

naxe config set-url postgresql://user:pass@localhost/naxe

PostgreSQL is the right choice when:

  • Multiple agents run concurrently against the same job graph
  • You want the task history to persist across machine restarts
  • You're running a team setup where multiple people share one naxe instance

Note: SQLite is single-writer by design. For multiple concurrent agents writing tasks, use PostgreSQL.

Authentication

By default, naxe runs in open mode — any caller is accepted and agent_id is self-reported. This is fine for personal local use.

To enforce identity and access control, register agents with API keys:

# Register an agent (first registration requires no key)
naxe config register-agent my-agent
# → Key: naxe_sk_...   Store this — it will not be shown again.

# Add the key to your MCP config
claude mcp remove naxe
claude mcp add --scope user --transport stdio naxe \
  --env NAXE_API_KEY=naxe_sk_... \
  -- naxe

Once any agent is registered, naxe enforces NAXE_API_KEY on every connection. The key carries the agent's identity — all tool calls are attributed to the registered name regardless of what the caller passes as agent_id.

Managing agents

naxe config list-agents           # Show all registered agents and their status
naxe config revoke-agent <name>   # Revoke an agent's key
naxe config register-agent <name> # Register a new agent (requires NAXE_API_KEY if others exist)

When to use auth

Use caseRecommendation
Personal local useOpen mode (no keys needed)
Ephemeral agent sessionsOpen mode (each agent owns its own naxe instance)
Multi-agent, shared PostgreSQLRegister each agent with a key
Team / shared deploymentRegister each user/agent with a key

Configuration

naxe config get-url          # Show current DB URL and where it came from
naxe config set-url <url>    # Save a DB URL to ~/.config/naxe/config
naxe config get-theme        # Show current TUI theme
naxe config set-theme <name> # Save theme (built-in: naxe, naxe-bold)
naxe config get-context      # Show the active context
naxe config set-context <name> # Set the active context

Environment variables take precedence over config files:

VariablePurpose
NAXE_DB_URLFull database URL (postgresql:// or file path)
NAXE_DB_PATHSQLite file path shorthand
NAXE_API_KEYAgent API key for authenticated deployments
NAXE_THEMETUI theme name
NAXE_CONTEXTActive context (workspace)

Context

Contexts let you partition jobs into isolated workspaces — for example, separating home and work tasks on a shared database. Context is a server-level setting; agents never see or set it directly.

# Set a context
naxe config set-context work

# Or via environment variable
NAXE_CONTEXT=work naxe

When a context is active, only jobs in that context are visible. Jobs created without a context are only visible when no context is set. To use multiple contexts, configure separate MCP server entries with different NAXE_CONTEXT values:

claude mcp add --scope user --transport stdio naxe-work \
  --env NAXE_DB_URL="postgresql://..." \
  --env NAXE_CONTEXT=work \
  -- naxe

claude mcp add --scope user --transport stdio naxe-home \
  --env NAXE_DB_URL="postgresql://..." \
  --env NAXE_CONTEXT=home \
  -- naxe

Tools

Naxe exposes 33 MCP tools grouped by function:

Job lifecycle

ToolDescription
create_jobCreate a new task graph job
get_job_statusFull snapshot: all tasks, progress counters, blocking jobs
list_jobsList jobs with per-job progress summaries
edit_jobRename a job
cancel_jobCancel a job and all pending tasks atomically
pause_jobPause a job (no new claims until resumed)
resume_jobResume a paused job
add_job_dependencyDeclare that one job must complete before another starts
set_job_concurrencySet or clear a max concurrent agent limit
set_worktree_pathsStore git worktree paths keyed by repo

Task execution

ToolDescription
add_tasksAdd tasks with dependencies. job_id is optional — omit it to auto-create a job.
get_next_actionsReturn all currently unblocked tasks (orchestrator use)
claim_taskAtomically claim a specific task
claim_next_actionAtomically find and claim the next unblocked task (worker use)
complete_taskMark done; returns newly unblocked tasks
fail_taskMark failed with optional reason and output
heartbeat_taskPrevent a long-running task from being reclaimed as stale
update_task_progressReport 0–100 progress on a task you own
cancel_taskCancel a single pending or in-progress task
edit_taskEdit metadata or dependencies of a pending task
requeue_taskReset a failed or cancelled task back to pending

Approval workflow

ToolDescription
request_approvalTransition an in-progress task to awaiting_approval
approve_taskApprove a task, marking it complete and unblocking dependents
reject_taskHard-fail a task awaiting approval
return_taskReturn a task to pending with feedback for the agent

Comments & audit

ToolDescription
add_task_commentAdd a comment to a task (agent or human)
get_task_commentsRetrieve comment history, optionally by approval round
get_task_eventsFull event history for a single task
get_job_audit_trailAll events across every task in a job
get_blocked_tasksList pending tasks blocked by incomplete dependencies

Templates

ToolDescription
create_job_templateSave a reusable task graph as a named template
list_templatesList all saved templates
instantiate_templateCreate a new job from a template

TUI

Naxe includes an interactive terminal UI for browsing jobs and tasks:

naxe ui

Keyboard shortcuts: Enter open job, A approval queue, N new job, E edit, X cancel, P pause/resume, F cycle filter, Q quit.

Design notes

  • SQLite is single-writer. Concurrent agents reading is fine; concurrent writes will serialize. Use PostgreSQL for true multi-agent parallelism.
  • Authentication is optional. Open mode (no registered agents) is the zero-config default. Once any agent is registered, all connections require a valid key.
  • agent_id is server-enforced when auth is enabled. With a registered key, the server ignores whatever agent_id the caller passes and uses the registered name instead. The audit trail is trustworthy.
  • Pre-1.0: breaking schema changes will require dropping and recreating the database. A proper migration system will be added before 1.0.

Run Tests

uv run pytest tests/ -v
Ver o original no GitHub

Bom para

Relacionados