abkus-code

AI coding agent for your terminal. Powered by Abkus Hub.

Works in any project directory, container, or CI environment.

📊 Comparativo Técnico e Diferenciais Estratégicos

Em comparação aos assistentes de linha de comando e agentes de código tradicionais do mercado, o abkus-code oferece vantagens arquiteturais únicas:

• 🚀 Roteamento Inteligente em 10 Tiers (@abkus/ai-core): Ao contrário de ferramentas convencionais que dependem de seleções manuais e fixas de modelo, o abkus-code classifica a complexidade do prompt em tempo real e encaminha a requisição para a combinação ideal de capacidades (Architect, Hyper, Fast, Pro, Easy), garantindo alta qualidade com máxima eficiência de tokens.
• 🛡️ Segurança e Confinamento de Caminhos: Toda operação de sistema de arquivos e execução de comandos no terminal é estritamente delimitada ao diretório do projeto ativado (allowedBasePaths), contando com lista de bloqueio de shell e sanitização automática de segredos (redactSecrets).
• 🎨 Visualização Colorida de Diffs (ANSI Unified Diffs): No modo de planejamento (plan mode), cada alteração de código é apresentada em formato unificado colorido no próprio terminal antes da execução física no disco.
• 🔗 Paridade e Conexão Nativa PWA (abkus-code serve): Atua como daemon local de alta performance fornecendo sincronização imediata com o Abkus Studio via token único de pareamento (/pair).

Install

npm install -g abkus-code

Usage

# Start interactive chat in current directory
abkus-code

# Continue last session
abkus-code --continue

# Dry-run (plan only, no file writes)
abkus-code --dry-run

# Use a specific workspace
abkus-code --workspace /path/to/project

# Serve local daemon for Abkus Studio PWA
abkus-code serve

Commands

| Command | Description | |---------|-------------| | abkus-code | Start interactive chat agent | | abkus-code serve | Start local HTTP daemon for Abkus Studio PWA | | abkus-code login | Sign in with your Abkus account (opens browser) | | abkus-code logout | Remove stored credentials | | abkus-code init | Create .abkus-code.json in current directory | | abkus-code doctor | Check environment and hub connectivity | | abkus-code loop <objective> | Run a one-shot autonomous task | | abkus-code test-qa <objective> | Browser QA loop (human-simulation tools only; no file writes) | | abkus-code ide | Start agent + open browser chat interface | | abkus-code review | Review current git diff for bugs and quality | | abkus-code cost | Show token usage and estimated cost | | abkus-code mcp | Start MCP server for IDE tools (--list prints browser/qa tool catalog) | | abkus-code status | Show agent status |

Chat commands

| Command | Description | |---------|-------------| | /mode auto\|code\|plan\|review\|ask | Switch agent mode | | /clear | Clear conversation history | | /compact | Compress old messages into a summary | | /cost | Show session token and cost stats | | /exit | Save session and quit |

Agent modes

• auto — detects intent from your message (default)
• code — execute changes directly
• plan — queue writes for confirmation before executing
• review — read-only analysis, no changes
• ask — pure chat, no file access

Tools

41 tools across 7 categories:

• Filesystem: read_file, write_file, read_multiple_files, apply_patch, move_file, delete_file, list_directory, scaffold_file
• Search: search_code (ripgrep), web_search, web_fetch
• Shell: run_command, run_pnpm
• Git: git_status, git_diff, git_add, git_commit, git_push, git_create_branch, git_restore, git_create_pr, git_merge
• Quality: run_typecheck, run_tests, run_lint, read_lints, find_references
• Browser: browser_start, browser_navigate, browser_click, browser_type, browser_resize, browser_screenshot, browser_describe_screenshot, browser_console, browser_network, browser_judge, browser_stop — scoped Playwright session, same token/CORS/redaction model as filesystem and exec. browser_navigate blocks loopback/link-local/private-network targets unless the URL matches this project's configured tools.targetOrigin (or abkus-code serve's --target-origin flag) — the one legitimate reason to point it at a local address. Pass comma-separated origins when the flow spans multiple local ports (e.g. app under test + Hub SSO IdP: --target-origin http://localhost:3002,http://localhost:3230). browser_describe_screenshot translates screenshots to text for models without vision.
• QA journal: qa_start_run, qa_record_finding, qa_finalize_report — durable findings for test-qa / Studio /runs

QA via MCP

Use the same browser + QA tools from Cursor (or any MCP client) without going through Abkus Studio:

# List tools (must include browser_* and qa_*)
abkus-code mcp --list

# HTTP transport (default port 3300) — GET / returns tool catalog
abkus-code mcp --transport http --port 3300

# stdio transport (JSON lines). List tools:
#   {"id":"1","method":"tools/list"}
# Call a tool:
#   {"id":"2","tool":"browser_start","args":{}}
abkus-code mcp --transport stdio

Example Cursor MCP config (stdio):

{
  "mcpServers": {
    "abkus-code": {
      "command": "abkus-code",
      "args": ["mcp", "--transport", "stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

Typical QA sequence via MCP: browser_start → browser_navigate → browser_screenshot / browser_judge → qa_record_finding → qa_finalize_report → browser_stop. Prefer abkus-code test-qa when you want the full autonomous loop; use MCP when another IDE agent should drive individual tools.

Configuration

Optional .abkus-code.json in your project root:

{
  "agentId": "my-agent",
  "tools": {
    "allowedBasePaths": ["/home/user/myproject"],
    "blockedPaths": [".env", ".ssh"],
    "shellBlocklist": ["rm -rf"]
  }
}

By default the agent is confined to the directory where it is started. Add parent directories to allowedBasePaths to allow reading across a monorepo.

Interactive PTY (Studio terminal)

abkus-code serve exposes an authenticated WebSocket at /v1/pty for interactive shells (used by Abkus Studio’s bottom terminal with xterm.js). One-shot POST /v1/exec remains available for the agent tool loop.

• Auth: ?token= (pairing token) or Authorization: Bearer …; Origin must match --studio-origin.
• Cwd: daemon --root (optional cwd query must stay inside root).
• Idle timeout: 10 minutes without IO.
• Unpair / DELETE /v1/pty: kills all open sessions.
• Status: GET /v1/pty/status → { available, sessions, wsPath }.

Native dependency (node-pty)

node-pty has no published linux-x64 prebuild. After pnpm install, the package must be allowed to run its install script and compile with Python + make + g++:

# already listed in root package.json pnpm.onlyBuiltDependencies + .pnpmrc.json
pnpm install
# if the binding is still missing:
pnpm rebuild node-pty

If the native module fails to load, /v1/pty/status reports available: false and Studio falls back to one-shot daemon exec.

Requirements

• Node.js 24+
• git
• ripgrep (rg) — for search_code tool
• An Abkus account
• Optional (interactive Studio terminal): node-pty native build (see above)