Localclaw

a local-first pentest agent for authorized security work

   /\_/\
  ( o.o )   Localclaw  v0.3.0
   > ^ <    local · offline · operator-grade

Localclaw is a terminal pentest assistant that runs entirely on your machine. It wraps a local LLM (via Ollama) in an Ink-based TUI with an agent loop, permission-gated tools, skills, and subagents — so you can use a real AI copilot for security work without sending anything to the cloud.

No API keys. No telemetry. No accounts. Pull your network cable and it still works.

Install

# 1. install ollama and pull a tool-capable model
ollama pull qwen2.5-coder:7b

# 2. install localclaw
npm install -g localclaw

That gives you two binaries: localclaw and the shorter claw.

Usage

claw                              # interactive mode
claw "scan localhost"             # launch with a starting prompt
claw --run nmap -sV localhost     # queue a direct bash command (gated)
claw --help                       # all flags

Inside the TUI, type / to browse commands or just talk to the agent. Every tool call requires your approval — press y to allow once, a to always allow, n to deny.

Features

• Local-first — Ollama backend, no cloud calls, no API keys, no telemetry
• Permission-gated — every tool call asks before running, with allow-once / always-allow / deny
• Streaming — token-by-token responses with live tool execution
• Skills — markdown files in commands/ become slash commands automatically
• Subagents — dispatch specialist agents (recon, web-tester, exploit-dev, report-writer, blue-team-advisor) via the task tool
• CodeGPT bridge — can call CodeGPT (or any compatible local AI) for code analysis
• Auto-start — Ollama boots automatically on launch
• Persistent tokens — lifetime token counter survives restarts
• CLI catalog — at startup, scans your PATH for 40+ known pentest tools and tells the agent what's available
• Session save — /save writes transcripts to loot/ as Markdown

Built-in commands

/help      show all commands         /tokens    show token usage
/skills    list loaded skills        /save      save transcript
/agents    list subagents            /clear     clear transcript
/tools     list available tools      /reset     reset session
/model     switch ollama model       /allow     show always-allowed
/models    list installed models     /revoke    drop grants
/cli       show detected pentest CLIs /web       open landing page
/install   install pentest toolchain  /codegpt   ask sibling local AI

Plus any markdown file in your commands/ directory — /engage, /recon, /webscan, /netscan, /report ship as defaults.

Subagents

Localclaw can dispatch specialist subagents via the task tool. Each is a markdown file with its own system prompt:

• recon-operator — passive + active reconnaissance
• vuln-hunter — map services to CVEs, OWASP, misconfigs
• web-tester — deep web app audit
• exploit-dev — minimal PoC exploits (authorized scope only)
• report-writer — PTES-shaped engagement reports
• blue-team-advisor — turn findings into detection rules
• scope-guard — scope validation for every action

Agent tools

• read_file write_file edit_file — file operations
• bash — run any shell command (permission-gated)
• grep list_dir — search and explore
• task — dispatch a subagent
• codegpt — ask the sibling CodeGPT server for code reasoning

Every tool requires operator approval. bash specifically shows the command in a code block before asking.

Requirements

• Node.js 18+
• Ollama running locally with a tool-capable model (qwen2.5-coder:7b is the default and recommended)
• Windows, macOS, or Linux — tested most extensively on Windows

Environment variables

• OLLAMA_HOST — default http://localhost:11434
• CPT_MODEL — default qwen2.5-coder:7b
• CODEGPT_HOST — default http://localhost:5050 (optional)
• CODEGPT_MODEL — default qwen2.5-coder:7b (optional)

Scope and safety

Localclaw is for authorized security testing only. The built-in system prompt refuses destructive techniques, mass targeting, and detection evasion for malicious purposes. It's designed for CTFs, pentest engagements with written scope, and defensive security research.

Run /engage to start a scoped engagement and the agent will refuse to act outside the declared scope.

License

MIT

Credits

Built with Ink, React, and Ollama. Architectural inspiration from the broader class of modern terminal AI assistants — specifically the patterns of streaming agent loops, markdown-based skills, and permission-gated tool use.