convez.ai
MCP Server
privateer-agent

privateer-agent

privateer-agent/privateer-agent

Ver no GitHub
InicialPluginScore · de 0 a 100

⚓ Provider-agnostic terminal coding agent — bring your own model. Switch between OpenRouter Anthropic, OpenAI & local Ollama with one command. Plan mode, checkpoints, MCP, hooks, sub-agents and a modal prompt, all on the Vercel AI SDK.

Instalação

$npx convez-ai privateer-agent/privateer-agent

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
9
Forks
0
Acompanhando
3
Saúde
37%
Último commit
há 4 dias
Versão
v0.15.8
Issues abertas
5
Contribuidores
1

README

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

Switch between OpenRouter, Anthropic, OpenAI, and local Ollama with one command. Built on the Vercel AI SDK, so tool-calling and streaming work identically across every provider — no model lock-in, no separate code paths.

Why Privateer?

  • No lock-in. Point it at a frontier model today and a local Ollama model tomorrow — /model swaps mid-session. Your config, commands, and agents come along for the ride.
  • The agent UX you already know. Plan mode, checkpoint/rewind, a modal prompt, slash commands, sub-agents, and project memory — but vendor-neutral.
  • Genuinely extensible. MCP servers, lifecycle hooks, custom commands, output styles, and sub-agents are all just files under .privateer/. No plugins to compile.
  • Zero binary deps. The file/search/shell tools are pure Node — nothing to install beyond node.

Highlights

  • A modal prompt with / command and @ file autocomplete, ! shell passthrough, # memory append, input history, optional vim mode, and ctrl-r history search
  • Layered settings.json (user → project → local → managed), custom slash commands and output styles as markdown files
  • Plan mode (read-only → present a plan → approve), checkpoint/rewind of conversation and files
  • Extensible: MCP servers (local stdio + remote HTTP/SSE, with interactive OAuth), lifecycle hooks, and custom sub-agents
  • Background shells, bounded parallel sub-agents, thinking display, structured compaction, and image attachment for vision-capable models

Quickstart

git clone https://github.com/privateer-agent/privateer-agent.git
cd privateer-agent
npm install
export OPENROUTER_API_KEY=sk-or-...     # one provider is enough
npm start                               # launches the interactive TUI

First run walks you through picking a provider and default model. From there, just type.

Contents

Requirements

  • Node.js ≥ 20
  • An API key for at least one provider (or a local Ollama install)

Install

npm install        # install dependencies
npm link           # optional: put `privateer` on your PATH

Or run directly without linking:

npm start          # launches the interactive TUI
# or
node bin/privateer.mjs

Configure a provider

Privateer reads credentials from environment variables or a config file.

Env vars (quickest):

export OPENROUTER_API_KEY=sk-or-...      # gateway to ~everything
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export OLLAMA_BASE_URL=http://localhost:11434/api   # optional; defaults to this

Config file — ~/.privateer/config.json (global) and/or ./.privateer/config.json (per project):

{
  "defaultModel": "openrouter:anthropic/claude-opus-4.8",
  "permissionMode": "default",
  "providers": {
    "openrouter": { "apiKey": "sk-or-..." },
    "anthropic":  { "apiKey": "sk-ant-..." }
  }
}

Override the config location with PRIVATEER_HOME.

Model routing

defaultModel handles most turns, but it's often the wrong tool for a particular one — it may not accept the file you dropped in, or you'd rather spend a cheaper model on a trivial question. The optional router block lets Privateer switch models per turn based on the turn's data type and shape:

{
  "defaultModel": "openrouter:minimax/minimax-m3",
  "router": {
    "vision":   "openrouter:google/gemini-2.5-flash",
    "document": "openrouter:anthropic/claude-opus-4.8",
    "audio":    "openrouter:google/gemini-2.5-flash",
    "video":    "openrouter:google/gemini-2.5-flash",
    "long":     "openrouter:anthropic/claude-opus-4.8",
    "fast":     "openrouter:openai/gpt-4o-mini",
    "longThreshold": 60000,
    "fastMaxChars": 280,
    "inlineTextMaxBytes": 65536,
    "auto": true
  }
}

Reference a file in the prompt — drag-drop, paste a path, or @-mention — and Privateer classifies it by modality and routes accordingly:

RouteChosen when the turn (or conversation) includes…
visionan image (.png .jpg .jpeg .gif .webp)
documenta PDF (.pdf)
audioaudio (.mp3 .wav .m4a .ogg .flac)
videovideo (.mp4 .mov .webm .mkv)
longthe estimated context exceeds longThreshold tokens (default: half of contextBudget)
fastthe prompt is ≤ fastMaxChars characters (and needs no attachment)
defaulteverything else (defaultModel)

Each attached file collapses to a chip — [Image #1], [PDF #2], [Audio #3], [Video #4] — while the file itself rides along to the model. Code/CSV/markdown and other text files aren't routed: they're read and inlined into the prompt (up to inlineTextMaxBytes; larger ones are left as a path for the agent's read tool).

Capability requirements outrank long/fast. A turn that needs a modality is routed to a model that can actually accept it — and routing is sticky: once a file is in the conversation, later turns stay on a capable model so the attachment is never replayed to one that can't read it. A turn that needs several modalities at once (say an image and a PDF) is routed to a model whose support covers all of them. When a turn is routed, the transcript shows a line like ↪ routed to gemini-2.5-flash · image input.

Hybrid auto-detect ("auto": true, the default): if you reference, say, a PDF but haven't set router.document, and your defaultModel can't read PDFs, Privateer auto-selects a capable model from a configured provider. Set the route explicitly to control exactly which model is used, or "auto": false to disable it (you'll get a one-line warning when nothing can handle the modality).

Usage

privateer                                   # interactive TUI with the default model
privateer -m openrouter:anthropic/claude-opus-4.8
privateer -c                                # resume the last session in this dir
privateer -p "summarize src/"               # headless one-shot, prints to stdout

Run /model (no argument) to browse the models each configured provider actually offers — the list is fetched live using the API key you entered, then filtered as you type. Onboarding ends on the same picker so you choose your default model up front.

You can also pass a model string directly as provider:model:

Example
openrouter:anthropic/claude-opus-4.8any model on OpenRouter
anthropic:claude-opus-4-8direct Anthropic
openai:gpt-5.5direct OpenAI
ollama:qwen3-coderlocal model

The prompt

The input is modal — the first character chooses what happens:

PrefixMode
(text)a normal prompt to the model
/a slash command — opens an autocomplete menu
@a file mention — fuzzy-completes paths from the cwd
!run a shell command locally and show its output (no model turn)
#append the rest of the line to PRIVATEER.md

Also: ↑/↓ history, ctrl-r reverse history search, emacs line editing (ctrl-a/e/u/w), ctrl-l to clear the screen, and \+Enter for a newline. Messages typed while the agent is busy are queued and run in order. /vim toggles modal (vim) editing. Reference an image file to attach it for vision-capable models — by @-mention (@screenshot.png), or by pasting a path anywhere in the prompt. Absolute paths and paths with spaces work too, quoted ("/Users/me/My Shot.png") or backslash-escaped (/Users/me/My\ Shot.png); a leading /path/... is treated as a file, not a command. Each referenced image collapses to a short [Image #1] chip in the transcript (numbered across the session) while the picture itself rides along to the model.

While the agent is working, press Esc to interrupt the turn (partial output is kept); Ctrl-C quits.

Slash commands

Built-ins (plus any custom commands you add):

Command
/help /doctor /confighelp, diagnostics, resolved settings layers
/model [spec] /provider /loginchoose a model, list providers, re-run onboarding
/permissions [mode] /cost /contextpermission mode, token usage, context window
/init /memorywrite/show PRIVATEER.md
/agents /mcp [logout] /hooksinspect sub-agents; MCP status / clear OAuth; hooks
/output-style [name] /vim /verbosepersona, modal editing, full tool output
/rewind /compact /clear /exportrestore a checkpoint, compact, clear, save transcript
/exitquit
  • /model — open a picker of each provider's live models (or /model provider:id to set one directly).
  • /init — the agent explores the repo and writes a PRIVATEER.md for you (/init --stub just drops an empty template, no model call).
  • /rewind — pick an earlier checkpoint and restore the conversation, the files, or both.
  • /compact — summarize older history to reclaim context (also happens automatically).

Tools

read · write · edit · glob · grep · bash · bash_output · kill_shell · todo · task · web_fetch · web_search — plus any tools exposed by connected MCP servers.

The file/search/shell tools are pure-Node (no external binaries required). Mutating tools (write/edit/bash) and network tools (web_fetch/web_search, MCP) go through the permission gate. todo maintains the live task list; task delegates an investigation to a sub-agent that returns a summary. bash can run detached with run_in_background; bash_output polls a background shell's new output and kill_shell stops it.

Customize & extend

Everything below is optional and lives under .privateer/ (project) or ~/.privateer/ (user); project files win. Settings merge across config.json → settings.json → settings.local.json (run /config to see the resolved chain).

  • Custom commands — .privateer/commands/<name>.md. The body is a prompt template ($ARGUMENTS, $1…$9); optional frontmatter sets description/argument-hint. They appear in /help and / autocomplete; subfolders namespace as dir:name.

  • Output styles — .privateer/output-styles/<name>.md swap the agent's persona. Switch with /output-style <name> (or default).

  • Sub-agents — .privateer/agents/<name>.md with frontmatter (description, tools, model). Invoke via the task tool's subagent_type; /agents lists them.

  • Hooks — a hooks section in settings.json runs shell commands on PreToolUse, PostToolUse, UserPromptSubmit, and Stop. A hook blocks by exiting 2 or printing {"decision":"block"}; UserPromptSubmit can inject additionalContext. /hooks lists them.

  • MCP servers — declare them in .privateer/mcp.json ({ "mcpServers": { … } }). Both local stdio servers ({ "command", "args", "env" }) and remote HTTP servers ({ "url", "headers?", "transport?" }) are supported; remote defaults to Streamable HTTP with a fallback to legacy SSE. Their tools are namespaced server__tool and gated like the rest. Remote servers authenticate by a static headers bearer token, or — when none is set — via interactive OAuth (PKCE + dynamic client registration): on a 401 Privateer opens your browser, catches the redirect on a loopback port, and caches the tokens (owner-only) under ~/.privateer/mcp-auth/. /mcp shows each server's connection and auth state; /mcp logout [server] clears saved OAuth.

    {
      "mcpServers": {
        "fs":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
        "github": { "url": "https://api.githubcopilot.com/mcp/" },
        "internal": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer $TOKEN" } }
      }
    }
    
  • Status line — set statusLine to a shell command; it receives session JSON on stdin and its stdout becomes the status line.

Permission modes

ModeBehavior
defaultprompt before edits and shell commands
acceptEditsauto-approve file edits; still prompt for other shell commands (the default)
bypassno prompts (also --dangerously-skip-permissions or --no-quarter)
planread-only; the agent presents a plan, then you approve to leave plan mode

At an approval prompt: y allow once · a always · n deny. In plan mode, after the agent presents its plan: a approve and exit plan mode · k keep planning.

Project context

Create a PRIVATEER.md in your repo (via /init) to give the agent standing context — conventions, architecture notes, anything it should always know.

Develop

npm run typecheck
npm test

Caveats

Privateer's agent core is built provider-agnostic from the ground up; a few areas are deliberately simplified for now:

  • Prompt caching and extended thinking are Anthropic-only. Ephemeral cache breakpoints and the thinkingBudget setting apply to direct Anthropic models and OpenRouter routes to anthropic/*. Other providers ignore them (a harmless no-op).
  • Checkpoints are in-memory. /rewind is a within-session undo; snapshots live in memory and aren't persisted across restarts.
  • Remote MCP OAuth uses a fixed loopback port (7777 by default; override with PRIVATEER_OAUTH_PORT) so the redirect URI stays stable across runs. Set PRIVATEER_NO_BROWSER=1 in headless environments to skip the auto-launch and use the printed URL.
  • Image attachment assumes vision support. Referenced images are sent as content parts; non-vision models will return an error.
  • Compaction estimates context size (~4 chars/token). The summary itself is schema-guided (goals / decisions / files / open threads), with a plain-text fallback, and the most recent messages are always kept verbatim.
  • web_search scrapes DuckDuckGo's keyless HTML endpoint. It needs no API key but is best-effort and can break if their markup changes. web_fetch is robust for known URLs.
  • Protected files (.env, .npmrc, shell rc files, …) always prompt before edit — except in bypass mode, which by definition skips all prompts.

Docs

  • Architecture — how the provider layer, agent loop, tools, and permissions fit together
  • Brand assets — the logo and icon set

License

MIT © Patrick

Ver o original no GitHub

Bom para

Relacionados