AI Coding Agent for Linux & Termux — a terminal-native coding agent that inspects your project, plans, edits code, runs commands and tests, and iterates until the task is done.

Zero runtime dependencies · Free tier included · No telemetry

A terminal UI that stays out of your way — chat, tool activity, and code render cleanly right where you work.

Contents

• Features · Free tier · Installation · Quick start · Command line · TUI commands
• Provider configuration · Skills · Agent files · Themes · Security model · Privacy
• Architecture · Development · Testing · Troubleshooting · Roadmap · License

Features

• Interactive TUI — chat, agent status, tool execution, diff viewer, input. Keyboard driven, mouse-aware, works on 80×24 terminals and survives resize. Scroll the chat with PgUp/PgDn, the mouse wheel, or ↑/↓ while the input line is empty.
• Agent loop — plan → inspect → tool call → result → review → fix → retry until done (with an iteration cap).
• Tools — read/write/edit files, list directories, search files, run shell commands, git, fetch web pages, and live web search out of the box (no key needed — searches relay through the VectorHead gateway; bring your own Exa/Serper/Brave key to use your own quota). Extensible via MCP servers (mcp__<server>__<tool>, local stdio JSON-RPC, always permission-ask).
• Research subagent — the task tool delegates a read-only subtask (map a flow, find all callers of X, survey a module) to a child agent that can only inspect the project and returns a dense factual report — wide exploration costs the main conversation one tool result instead of dozens of read/search calls.
• Skills — 14 bundled, agentskills.io-format skills with progressive disclosure (list_skills / read_skill tools, /skills in the TUI); drop your own into ~/.vector/skills/ or .agents/skills/.
• Agent files — SOUL.md / MEMORY.md / USER.md / AGENTS.md auto-seeded in ~/.vector/ and injected into the system prompt (identity, notes, preferences, project rules).
• Security first — command policy classifies every shell command (SAFE / ASK / DANGEROUS / BLOCKED), permission prompts before risky actions, --yolo mode with warnings, and API keys are never printed or persisted to sessions.
• Multi-provider — OpenAI, Anthropic, Gemini, OpenRouter, Ollama, and any OpenAI-compatible custom endpoint — unlimited side-by-side providers with per-provider keys, models and headers.
• Sessions & memory — conversations persist to ~/.vector/sessions/; a relaunch in the same project resumes the conversation automatically (agent keeps the last replies in context), /continue resumes any session, and Ctrl+L//clear starts fresh.
• Context management — only relevant context is sent to the model, with compaction (/compact).

Free tier (zero config)

Install and chat — no account, no API key:

npm install -g agen-vektor
vector

The default provider is vectorhead-free (model glm-5.3-flash, 40 free models via /model). The shared provider key stays server-side; web search works through the same gateway out of the box. Bring your own provider key at any time via /connect.

Installation

Requirements: Node.js 20+ and npm (Termux: pkg install nodejs).

One-shot installer (recommended)

No Node.js/npm yet? The installer sets up Node 20+ & npm (apt on Debian/Ubuntu, pkg on Termux) and then installs VectorHead for you:

bash <(curl -fsSL https://raw.githubusercontent.com/clickmamaheti-prog/vector-agent/main/install.sh)

From npm

npm install -g agen-vektor
vector

Update (existing install)

Sudah install VectorHead sebelumnya? Tinggal update paket global npm-nya lalu verifikasi versi:

npm install -g agen-vektor@latest
vector --version

Config lama aman: model default yang sudah usang (glm-5.3-flash dst.) otomatis termigrasi saat aplikasi pertama kali dijalankan setelah update. Tidak ada langkah manual.

From source

git clone https://github.com/clickmamaheti-prog/vector-agent
cd vector-agent
npm install
npm run build
npm link   # makes `vector` available on your PATH
vector

Termux (Android)

pkg update && pkg upgrade
pkg install nodejs git
npm install -g agen-vektor
vector

Vector Agent has zero runtime dependencies and does not assume systemd, sudo, apt, or a desktop GUI — everything runs in a plain terminal.

Quick start

cd my-project
vector "Perbaiki error authentication pada project ini"

or start the TUI and type your task:

vector

Command line

| Command | Description | |---|---| | vector | Start the interactive terminal UI | | vector "task" | Start TUI and run the task immediately | | vector --model MODEL | Set the model | | vector --provider P | Set provider: openai, anthropic, gemini, openrouter, ollama, custom | | vector --theme NAME | Set theme: built-in or ~/.vector/themes/<name>.json | | vector --continue | Continue the most recent session | | vector --session NAME | Use/resume session NAME | | vector --plan | Show a plan before executing | | vector --yolo | Skip permission prompts for ask-level actions (with warning) | | vector --version / --help | Version / help |

Generic environment variables: VECTOR_API_KEY, VECTOR_API_URL, VECTOR_MODEL, VECTOR_PROVIDER, VECTOR_THEME, VECTOR_HOME, VECTOR_AUTO_APPROVE (=1 auto-approves ASK-level permission prompts, for automated runs/tests; dangerous actions still prompt), VECTOR_ASCII (=1 forces ASCII safe mode — glyphs map to 1-column ASCII so CJK/Termux fonts never tear the layout; auto-on for zh/ja/ko locales and Termux, =0 opts out on desktop).

TUI commands

Type / inside VectorHead — suggestions filter as you type:

| Command | Description | |---|---| | /help | Show help — /help all lists every command | | /connect | Configure provider: pick built-in / add custom API (/provider, /setup are aliases) | | /provider-remove | Remove the stored provider key (and custom URL/name) so you can re-enter fresh values | | /model | Select a model — auto-fetches the live model list from the provider | | /theme | Select a theme | | /session | Browse saved sessions | | /session-name | Set session name (arg optional) | | /settings | Show configuration | | /status | Show agent status | | /clear | Clear the conversation (keeps the session) | | /new | Start a fresh conversation — rotates to a brand-new session (the old one is kept on disk) | | /reset | Fresh conversation — old session file deleted from disk | | /continue | Continue the current/last session | | /soul /memory /user /agents | Edit agent files (SOUL/MEMORY/USER/AGENTS.md) | | /skills | List installed skills | | /mcp | Probe a configured MCP server and list the tools it provides | | /diff | Show diff viewer | | /git | Run git status | | /compact | Compact context (truncate old messages) | | /yolo | Toggle permission mode | | /exit | Quit |

Provider configuration

Set an API key via environment variable:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=...

Or inside VectorHead: /connect → pick provider → paste key (stored masked in ~/.vector/credentials.json, permissions 0600).

Custom API (OpenAI-compatible)

export VECTOR_API_URL=https://example.com/v1
export VECTOR_API_KEY=your-key
vector --provider custom --model deepseek-v3

The provider speaks /v1/chat/completions (and /models). Anthropic and Gemini protocols for custom endpoints are documented as adapters; OpenAI-compatible endpoints are fully supported.

Any number of OpenAI-compatible providers can be defined side by side in ~/.vector/config.json under providers:

{
  "provider": "bitdeer",                  // ACTIVE provider id
  "model": "deepseek-ai/DeepSeek-V4-Flash",
  "providers": {
    "bitdeer": {
      "name": "BitDeer",
      "options": {
        "baseURL": "https://api-inference.bitdeer.ai/v1",
        "apiKey": "{env:BITDEER_API_KEY}"   // or a plain key, or omit and store via /connect
      },
      "models": {
        "deepseek-ai/DeepSeek-V4-Flash": { "name": "DeepSeek V4 Flash" }
      }
    },
    "groq2": {
      "name": "Groq 2",
      "options": { "baseURL": "https://groq2.example.com/v1" }
    },
    "agentrouter": {
      "name": "AgentRouter",
      "model": "deepseek-v4-flash",          // default model when this provider is active
      "options": {
        "baseURL": "https://agentrouter.org/v1",
        // Gateways that filter by client (AgentRouter only accepts official
        // AI clients) need a spoofed User-Agent on every request:
        "headers": {
          "User-Agent": "codex_cli_rs/0.101.0 (Mac OS 26.0.1; arm64) Apple_Terminal/464",
          "Originator": "codex_cli_rs"
        }
      }
    }
  }
}

• provider is the active id — a built-in, the legacy custom slot, or any key of providers. Keys are per provider id: store each under its own id in ~/.vector/credentials.json (0600) via /connect, inline them in options.apiKey, or reference an env var with "{env:NAME}".
• options.headers adds extra HTTP headers to every request of that provider (e.g. a User-Agent required by a client-filtering gateway like AgentRouter). Values may be plain strings or "{env:NAME}" templates; headers referencing a missing env var are dropped.
• model is the default model for that provider: when the provider becomes active (/connect, --provider, or VECTOR_PROVIDER), the active model automatically follows it unless an explicit --model / VECTOR_MODEL was given. Handy when each provider speaks its own model ids (e.g. AgentRouter uses deepseek-v4-flash while BitDeer uses deepseek-ai/DeepSeek-V4-Flash).
• /connect lists built-ins + every configured custom and offers Add custom provider (id → name → base URL → key). /model then auto-discovers models from the endpoint's /models route and falls back to the models map above.
• The old single-custom setup (provider: "custom" + apiUrl/customName
  • key under custom) keeps working unchanged.

Switch at runtime with /connect, or per-run with VECTOR_PROVIDER=bitdeer vector … / --provider bitdeer.

Skills

VectorHead ships a built-in skill system (agentskills.io format — YAML frontmatter + markdown body) with progressive disclosure: the agent sees a one-line catalog first and loads a skill's full body only when needed via the list_skills / read_skill tools.

14 bundled skills: verify-node-project, safe-git-workflow, debug-loop, fetch-docs, secure-secrets, systematic-debugging, test-driven-development, codebase-inspection, requesting-code-review, spike, simplify-code, grounded-citations, blocked-page-recovery, humanize-writing.

Install your own (multi-root resolution):

| Root | Scope | |---|---| | ~/.vector/skills/<name>/SKILL.md | personal — always active | | <project>/.agents/skills/<name>/SKILL.md | project — active when running from that project | | ~/.agents/skills/<name>/SKILL.md | personal (standard npx skills layout) |

Browse in the TUI with /skills.

Agent files

Markdown files auto-seeded in ~/.vector/ (never overwritten by upgrades):

| File | Purpose | |---|---| | SOUL.md | Agent identity — slot #1 of the system prompt | | MEMORY.md | Persistent notes the agent keeps across sessions | | USER.md | What the agent knows about you | | AGENTS.md | Project rules (also read from the project root, like this repo's own) |

Edit via the TUI (/soul, /memory, /user, /agents) or any editor. Size is capped per file to keep prompts lean.

Themes

VectorHead has its own theme system: pick a built-in theme, or drop your own JSON files into ~/.vector/themes/ — no restart, applies on the fly.

vector --theme tokyonight     # one-off
# or persist it:
echo '{ "theme": "nord" }' >> ~/.vector/config.json   # (merge manually)
# or inside the TUI: /theme
# or env: export VECTOR_THEME=matrix

Built-ins: vectorhead (default — the signature orange & gold VectorHead palette), nord, tokyonight, gruvbox, catppuccin, one-dark, matrix.

A theme is a JSON file with an optional defs block of reusable colors plus a semantic theme block. Color values may be hex (#88C0D0), ANSI palette indexes (3 for 0–255), references ("nord8" or "primary"), dark/light variants ({ "dark": "#000", "light": "#fff" }), or "none" (terminal default).

{
  "defs": { "brand": "#9EFC62" },
  "theme": {
    "primary": "brand",
    "text": "#f1f5f9",
    "textMuted": "#acb3bf",
    "background": "#0b0f14",
    "backgroundPanel": "#141a21",
    "border": "#2b3542",
    "error": "#ff6b6b",
    "warning": "#ffa500",
    "success": "#9EFC62"
  }
}

Save it as ~/.vector/themes/my-theme.json, then /theme (or vector --theme my-theme) to use it. Semantic keys and their effect: primary (brand accent), accent/markdownHeading (headings, prompt), text, textMuted, textFaint, markdownCode, border/borderActive, error/warning/success/info, diffAdded/ diffRemoved/diffContext, backgroundPanel/backgroundElement. Unknown keys and unresolvable colors are ignored, so partial themes keep the default palette for anything you don't override.

Hex colors are emitted as truecolor (24-bit) escapes — terminals need COLORTERM=truecolor for full fidelity (most modern terminals). ANSI palette indexes and vectorhead work everywhere.

Security model

Every shell command is classified:

• SAFE — read-only commands run without prompting (ls, cat, git status, …)
• ASK — prompts for confirmation (npm install, npm test, git commit, …)
• DANGEROUS — prompts with a warning (rm -rf, chmod, git push, …)
• BLOCKED — refused outright (rm -rf /, mkfs, shutdown, forced pushes, …)

--yolo auto-approves ASK-level actions but still prompts for DANGEROUS and refuses BLOCKED ones. API keys are never printed to the terminal, logs, diffs, or session history.

Privacy

VectorHead collects nothing. No telemetry, no analytics, no crash reporting, no usage tracking — there is no code in the app that could phone home. Every network destination in the source is auditable:

| Destination | When | |---|---| | Your configured AI provider (OpenAI, Anthropic, Gemini, OpenRouter, Ollama, custom) | Only when you chat — with your own API key | | vector-tui.methatech.eu.org (VectorHead Free gateway) | Only if you pick the free tier; the shared provider key stays server-side, users never see it | | Brave / Exa / Serper | Only when you use the web-search tool with your own key | | vector-tui.methatech.eu.org/v1/web-search | Web search when you have NO search key of your own — the query is relayed by the gateway; your own key, when set, always takes precedence and bypasses the relay | | vector-tui.methatech.eu.org/v1/e2b/run | e2b_run tool — run a command in a disposable cloud sandbox (E2B VM) when the local machine is too weak/restricted; relayed by the gateway, no E2B key needed client-side | | Raw model catalog (public JSON) | To populate the free-tier model list |

Stored locally (all in ~/.vector/): config.json (preferences, no secrets), credentials.json (only keys you enter, file mode 0600), sessions, memory, logs. Nothing else is written anywhere.

No device identity. The app does not generate a device id or send any tracking header (the old anonymous device-id + X-Vector-Device pair was fully removed in 0.3.14).

The agent guards itself against secrets — its own file tools refuse to read or write .env, private keys, credentials.json, kubeconfig, and similar files (override only via explicit VECTOR_ALLOW_SENSITIVE=1), so a prompt cannot accidentally exfiltrate them.

Architecture

src/
├── cli/          argument parsing, keyboard, bootstrap
├── tui/          terminal UI: chat, input, statusbar, diff, components
├── agent/        agent loop, planner, context, memory, prompts, session, skills
├── providers/    AIProvider interface + OpenAI/Anthropic/Gemini/OpenRouter/Ollama/Custom
├── tools/        tool registry + filesystem/shell/search/git/web/skills
├── security/     command policy + permission manager
├── config/       config, credentials, model catalog, free tier
└── utils/        terminal (ANSI), logger, paths

Providers and tools are pluggable: adding one never touches the agent core.

Development

npm run dev       # run from source with tsx
npm run build     # compile TypeScript
npm test          # run unit tests (node:test)
npm run typecheck # tsc --noEmit

Testing

Unit tests cover providers, the agent loop, the tool registry, filesystem tools, the command policy, config, credentials, sessions, context manager, keyboard, diff, and CLI helpers.

npm test
npm run build

Troubleshooting

• "No API key configured" — set the relevant *_API_KEY env var or run /connect in the TUI. On the free tier this never appears — a default free provider is pre-configured.
• "401" / auth failed — check the key, or for OpenRouter use OPENROUTER_API_KEY.
• "model not found" on the free tier — the free catalog rotates; run /model to pick from the live list.
• "Rate limited (429) / cooling down" — VectorHead retries automatically with backoff, and the free gateway cools down briefly instead of burning the shared key. Switch to another free model via /model and retry.
• Nothing happens on vector in Termux — make sure your terminal is a TTY and TERM is set (e.g. export TERM=xterm-256color). If glyphs look broken (█ everywhere, torn logo), ASCII safe mode is already default-on; desktop users can opt back in with VECTOR_ASCII=0.
• Runs out of iterations — open /settings in the TUI and press +/- (or PgUp/PgDn, or type a number) to raise maxIterations — persisted to ~/.vector/config.json — or refine the request.

Roadmap

• Interactive diff approval before edits in safe mode
• Persistent permission rules per project
• Windows support (WSL-focused)

MCP (Model Context Protocol)

VectorHead can extend its own toolset with local MCP servers — small programs spawned on the same device the agent runs on (Termux included), speaking JSON-RPC 2.0 over stdio. No SDK, no extra dependencies, no hosting: this is the same spawn pattern the shell tool uses (detached process group, per-request timeouts, kill-on-exit — an exiting VectorHead never leaves orphaned MCP processes behind).

Configure servers in ~/.vector/config.json (mode 0600, so per-server env secrets stay private):

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

• On startup every enabled server is spawned, the initialize handshake completes, and its catalog is imported into the tool registry as mcp__<server>__<tool> (e.g. mcp__everything__echo) — collision-free with built-in tools.
• A broken/garbage server is skipped with a warning — it can never prevent the agent from starting.
• /mcp in the TUI probes a configured server on demand and lists the tools it would provide.
• Trust model: MCP tools are third-party code. Every MCP tool runs with permission: 'ask' — even in --yolo mode you approve each call — and results are truncated like shell output. Tool descriptions come from the server and are treated as untrusted data (prompt-injection surface).

Changelog

0.3.34

• Research subagent (task tool) — the agent can now delegate a focused, read-only research subtask ("find every caller of X", "map the auth flow") to a child agent that can only inspect the project (read/list/search/glob/semantic_search — nothing else) and returns a dense factual report. Wide exploration costs the main conversation ONE tool result instead of dozens — the agent stays sharp on big tasks. No recursion, own iteration budget (≤25), report capped, dedicated research prompt.
• Default free model = vector.5.3 (jalur Atria). The old z-ai/glm-5.3-free default now 404s on the gateway; existing installs on a dead id are migrated automatically.
• Fix: model choice no longer reverted on launch. The free-tier startup repair used to overwrite your selected model back to the compiled default every launch — an explicit model that is still servable in the live catalog now survives.
• Fix: search_files is literal (-F). Queries with regex metacharacters (e.g. login() no longer make ripgrep fail — a text search tool must search text.

0.3.33

• Boot splash "Loading System . . ." before the TUI dashboard. Launching vector now shows a brief boot screen — brand banner, three loading steps (Config → Environment → Provider), a braille spinner and progress bar, then "System ready" — before the whole block is cleanly erased and the chat TUI enters alt-screen. Zero scrollback residue.
• Zero dependencies, Termux-safe. The splash follows VECTOR_ASCII (spinner becomes |/-\ in ASCII safe mode), never blocks process exit (timer is unref'd), and failure to build the agent still clears the splash before the error propagates.
• Controls: VECTOR_SPLASH=0 disables it entirely; VECTOR_SPLASH_STEP_MS (default 450) and VECTOR_SPLASH_HOLD_MS (default 900) tune the timing.

0.3.30

• Thinking card matches Freebuff thinking.tsx exactly — no mid-run color flip-flop. The reasoning body renders muted (#acb3bf) italic in BOTH streaming and completed states; only the header (dot + bold "Thinking") is foreground-white. Previously the body flipped from white (streaming) to muted (done), which read as the card changing color during a run.
• Expanded thinking view is raw muted italic with word wrap. The in-card markdown re-render was removed — headings/inline code no longer paint their own colors inside the card (the mixed-color expanded view read as noise). Markdown markers in reasoning now show as-is, uniformly styled.

0.3.15

• Thinking cards are segmented per completed agent step. Reasoning for each step (think → tool → think → tool) now renders as its own • Thinking card instead of stacking every step's reasoning into one ever-growing card — stale reasoning no longer appears to "leak" below the live thinking preview during multi-step tasks like web research.
• Streaming answers keep the guarded mergeStreamDelta accumulation across all providers (no more doubled final text on gateways that resend the full text).

0.3.14

• Removed the anonymous device-id / X-Vector-Device tracking pair entirely — no device identity is generated or sent.
• Emoji-aware character widths: /connect picker borders align on CJK/emoji terminals.

License

MIT