convez.ai
MCP Server
EngineerProjects

nexus-engine

EngineerProjects/nexus-engine

Ver no GitHub
BomPluginScore · de 0 a 100

Headless agentic runtime in Go, multi-provider LLM, sandboxed tools, MCP client, plan mode & permissions. Drop-in Anthropic API compatible.

Instalação

$npx convez-ai EngineerProjects/nexus-engine

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
5
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 1 semana
Versão
v1.16.0
Issues abertas
46
Contribuidores
1

README

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


🖥️ Terminal UI

nexus chat drops you into a full-featured terminal interface built for long-running agent sessions.

Keyboard shortcuts: ctrl+p settings · ctrl+m models · ctrl+s sessions · ctrl+, providers · ctrl+n new session · ctrl+t tasks · ctrl+u copy last response · ctrl+y toggle yolo · ctrl+o open editor · ctrl+g help · ctrl+c quit

Clipboard note (Linux): selection copy works best when wl-clipboard (Wayland) or xclip/xsel (X11) is installed. Without a system clipboard backend, Nexus can request terminal clipboard access but cannot guarantee a real system copy.

Compaction note: transcript compaction is automatic today. A dedicated manual compact action is planned for the TUI once the runtime exposes a real manual-compaction hook.


🔀 Three Ways to Use It

1. 💻 CLI — nexus

An AI agent in your terminal. Multi-provider, local-first, skills-aware.

Build from source

git clone https://github.com/EngineerProjects/nexus-engine
cd nexus-engine
make build           # produces bin/nexus and bin/nexus-grpc

Add bin/ to your PATH, or copy bin/nexus to /usr/local/bin:

export PATH="$PATH:$(pwd)/bin"
# or
sudo cp bin/nexus /usr/local/bin/nexus

Configure a provider

nexus config --provider anthropic --api-key sk-ant-...
nexus config --model anthropic:claude-sonnet-4-20250514

nexus config --print

Run

nexus chat                                        # interactive TUI session
nexus chat --resume <session-id>                  # resume a specific session
nexus chat --continue                             # resume the most recent session
nexus run "list all TODO comments in this codebase"  # one-shot task
nexus sessions list                               # browse past sessions
nexus sessions list --status active               # active sessions only
nexus help                                        # full command reference

Sessions are persisted locally in SQLite. Skills are loaded from .nexus/skills/ in your project. The full tool set is available: file edits, sandboxed bash, web search, browser, MCP servers, sub-agents.


2. 🌐 gRPC Server

Run nexus-engine as a gRPC service and generate clients for any language.

# Development
ANTHROPIC_API_KEY=sk-ant-... go run ./cmd/grpc

# From build
ANTHROPIC_API_KEY=sk-ant-... ./bin/nexus-grpc

Server starts on :50051. The contract lives in pkg/grpc/proto/nexus.proto. Generate a client for Python, TypeScript, Java, Rust, or any gRPC-supported language:

# Python
python -m grpc_tools.protoc -I pkg/grpc/proto --python_out=. --grpc_python_out=. nexus.proto

# TypeScript
npx grpc-tools --js_out=. --grpc_out=. pkg/grpc/proto/nexus.proto

One runtime. Every language.


3. 📦 Go SDK

Embed the full runtime in your own Go application.

go get github.com/EngineerProjects/nexus-engine/pkg/sdk
import "github.com/EngineerProjects/nexus-engine/pkg/sdk"

client, err := sdk.NewClient(&sdk.ClientConfig{
    APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    Model:  sdk.ModelIdentifier{Provider: "anthropic", Model: "claude-sonnet-4-20250514"},
})
if err != nil {
    log.Fatal(err)
}
defer client.Close()

session, _ := client.CreateSession(ctx)
resp, _ := session.SubmitMessage(ctx, "Write a Go HTTP handler for /health")
fmt.Println(resp.Content)

📊 How Nexus Engine Compares

Featurenexus-engineClaude Agent SDKOpenAI Agents SDKLangGraphCrewAI
LanguageGoPython/TSPythonPythonPython
Single binary (no deps)✅❌❌❌❌
CLI included✅❌❌❌❌
gRPC server (any language)✅❌❌❌❌
Multi-provider✅ (15)❌ Claude only❌ OpenAI only✅✅
MCP client✅✅✅Partial❌
Sandboxed bash (Landlock)✅✅❌❌❌
Skills system✅❌❌❌❌
Built-in RAG✅❌❌❌❌
Browser automation✅✅❌❌❌
Session persistence✅❌❌✅❌
OTel tracing✅❌❌✅❌
Open-source licenseApache 2.0MITMITMITApache 2.0

✨ Capabilities

CapabilityDetails
🌍 Multi-provider15 providers: Anthropic, OpenAI, Gemini, Mistral, DeepSeek, Ollama, OpenRouter, AWS Bedrock, GCP Vertex, Azure Foundry, Codex, MiniMax, Z.ai, OpenCode, Cloudflare Workers AI
🛠️ 60+ built-in toolsFile read/write/patch, bash (Landlock sandbox), web search, web fetch, browser (Playwright), grep/glob, LSP, sub-agents, RAG, tasks, memory, worktree, notebooks, image generation, TTS/STT
🔌 MCP clientUniversal MCP client: plug in any MCP server (GitHub, Postgres, Slack, Docker, Notion, ...)
⚡ SkillsMarkdown instruction files injected into the system prompt: encode your team's conventions and domain expertise
🎯 Execution modesexecute (default), plan (review before act), pair_programming (collaborative)
🔒 Permission enginePer-tool deny rules, auto-mode LLM classifier, configurable per session (auto / acceptEdits / onRequest / bypass / never)
💾 Session persistenceSQLite-backed multi-turn sessions, resumable across restarts
📡 StreamingText chunks + structured runtime events (tool calls, plan events, permission requests, token usage)
🧠 Long-context compactionAutomatic context compression when approaching the model's window (configurable threshold)
📉 ObservabilityPrometheus metrics + OpenTelemetry tracing (OTLP gRPC export, no-op when endpoint not set)

🗂️ Repository Structure

nexus-engine/
├── cmd/
│   ├── cli/              ← nexus CLI entrypoint (TUI + one-shot commands)
│   └── grpc/             ← gRPC server entrypoint
├── pkg/                  ← public API (safe to import from outside)
│   ├── sdk/              ← Go SDK: Client, sessions, streaming, callbacks
│   ├── types/            ← shared types: Message, ToolUse, TokenUsage, ...
│   ├── agent/            ← agent definitions, built-in registry
│   ├── providers/        ← LLM provider abstraction, routing, fallback
│   ├── mcp/              ← MCP client: stdio, SSE, HTTP transports
│   ├── rag/              ← chunking, embedding, hybrid vector search
│   ├── skills/           ← skill loading, frontmatter parsing, injection
│   ├── memory/           ← in-session state, compaction strategies
│   ├── web/              ← web search, fetch, browser (Playwright)
│   ├── storage/          ← artifact store: S3, local filesystem
│   ├── vector/           ← vector DB abstraction
│   ├── contract/         ← Tool interface, CallResult, registry
│   ├── auth/             ← provider auth abstraction, OAuth device flow
│   ├── workspace/        ← sandbox path resolution, workspace layout
│   ├── monitoring/       ← Prometheus metrics, OTel spans
│   ├── docling/          ← PDF/DOCX/audio conversion via docling-serve
│   ├── grpc/             ← proto definitions and generated code
│   └── config/           ← app-level config from env
└── internal/             ← private implementation (do not import directly)

nexus-ai and any third-party consumer must import pkg/* only, never internal/*.


🌐 Supported Providers

Provider IDServiceAuth
anthropicAnthropicANTHROPIC_API_KEY
openaiOpenAIOPENAI_API_KEY
geminiGoogle GeminiGOOGLE_API_KEY
mistralMistral AIMISTRAL_API_KEY
deepseekDeepSeekDEEPSEEK_API_KEY
ollamaOllama (local)none
openrouterOpenRouterOPENROUTER_API_KEY
bedrockAWS BedrockAWS_ACCESS_KEY_ID + region
vertexGCP Vertex AIANTHROPIC_VERTEX_PROJECT_ID + region
foundryAzure AI FoundryANTHROPIC_FOUNDRY_API_KEY
codexChatGPT Pro (OAuth)device-code flow
minimaxMiniMaxMINIMAX_API_KEY
z-aiZ.aiZ_AI_API_KEY
opencodeOpenCode ZenOPENCODE_API_KEY
workers-aiCloudflare Workers AICLOUDFLARE_API_KEY

Full model listings and capabilities: docs/providers.md.


🚀 Quick Start

# 1. Clone and build
git clone https://github.com/EngineerProjects/nexus-engine
cd nexus-engine
make build                    # produces bin/nexus and bin/nexus-grpc
export PATH="$PATH:$(pwd)/bin"

# 2. Set your API key and model
nexus config --provider anthropic --api-key sk-ant-...
nexus config --model anthropic:claude-sonnet-4-20250514

# 3. Start chatting
nexus chat                          # new session
nexus chat --continue               # resume last session
nexus chat --resume <session-id>    # resume a specific session

# One-shot task in the current directory
nexus run "list all TODO comments in this codebase"

# Start the gRPC server (port 50051)
ANTHROPIC_API_KEY=sk-ant-... ./bin/nexus-grpc

No API key? Use Ollama for free local inference: nexus config --provider ollama --model ollama:llama3.2 (requires Ollama running locally)


⚡ Skills

Skills are Markdown files that encode expertise injected into the agent's system prompt at runtime.

.nexus/skills/
  go-conventions.md     # "always use context.Context as the first parameter..."
  git-workflow.md       # "never commit to main, always open a PR, squash before merge..."
  security-rules.md     # "never log secrets, validate all external input at boundaries..."

The official skill collection is nexus-skills, installable from any URL directly from the CLI.


🔌 MCP

Any MCP server is immediately usable — no additional development needed.

client, _ := sdk.NewClient(&sdk.ClientConfig{
    MCPServers: []sdk.MCPServerConfig{
        {Name: "github",   Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-github"}},
        {Name: "postgres", Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-postgres", "postgresql://..."}},
        {Name: "slack",    Command: "npx", Args: []string{"-y", "@modelcontextprotocol/server-slack"}},
    },
})

🏗️ Architecture

Full architecture diagrams (Mermaid): docs/vision/diagrams.md.


🧩 Building a Product on Top

nexus-engine is the headless runtime — no users, no billing, no access control.

nexus-ai is the full production platform built on top: multi-user auth, organizations, workspaces, per-user provider credentials, REST + SSE HTTP API, desktop app, and more — all open-source (AGPL-3.0).


📖 Documentation

DocWhat it covers
Vision & RoadmapProject idea, design principles, Level 1->2->3 roadmap
ArchitectureSystem design, layer diagrams, query loop state machine
SDK GuideClientConfig, sessions, streaming, callbacks, MCP
ToolsBuilt-in tools reference, permission pipeline
ProvidersMulti-provider routing, retry, circuit breaker
Prompt SystemSection assembly, stage overlays, cache control
SkillsSkills system, loading order, injection
Transports & SetupgRPC setup, proto codegen, env vars
Multi-Agent TeamsAgent profiles, mailbox, dispatcher, TeamBus

🛠️ Development

First-time setup

# Linux / macOS — installs all dependencies, builds, wires git hooks
make setup

# Windows (PowerShell — make is not available by default on Windows)
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

make setup handles everything: Go version check, ripgrep, uv, Python venv with docling-serve, and the final build.

Daily commands

make build         # build CLI and gRPC binaries to bin/
make test          # run all tests
make test-race     # run tests with race detector
make lint          # golangci-lint
make fmt           # gofmt
make hooks         # (re-)install git pre-commit hooks
make install-deps  # install ripgrep only (included in make setup)
make install-python  # install/update the Python venv + docling-serve only
make start-docling   # start docling-serve manually (auto-started by nexus chat)

Runtime data directory

Nexus stores sessions, config, and the Python venv under a platform-appropriate directory:

OSDefault path
Linux~/.config/nexus-cli/ (respects $XDG_CONFIG_HOME)
macOS~/.config/nexus-cli/
Windows%APPDATA%\nexus-cli\

Override with NEXUS_RUNTIME_ROOT=/your/path nexus chat.

Runtime dependencies

ripgrep — the glob and grep tools require ripgrep (rg). Included in make setup; install separately with make install-deps.

docling-serve (optional) — enables the read_document_url tool for PDF/DOCX conversion. Included in make setup via uv (no system Python required). Nexus auto-starts it on launch when installed.

OS compatibility

Linux — primary development and testing platform. Fully supported.

macOS — code is written to support macOS and basic testing has been done, but macOS support is not yet fully validated. If you hit an issue, please open a report.

Windows — PowerShell setup script included and paths are handled (%APPDATA%), but Windows support has not been tested yet. Contributions and test reports welcome.

See CONTRIBUTING.md for the full contribution guide.


🔒 Security

To report a vulnerability, see SECURITY.md.


📄 License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados