pawnlogic 0.0.6

A fully autonomous terminal AI agent — multi-model routing, persistent memory, real tool execution

English | 中文

🤖 PawnLogic

A fully autonomous terminal AI agent — multi-model routing, persistent memory, real tool execution, and session management. Built for developers and security researchers.

System Requirements

• Linux or WSL2
• Python 3.10+
• pip and git
• ~/.local/bin in PATH if you want the global pawn command

⚡ Quick Start

Option A — pip install (recommended)

pip install pawnlogic
pawn   # first run launches the API configuration wizard

Option B — from source

git clone https://github.com/john0123412/PawnLogic.git && cd PawnLogic
python3 -m venv venv && source venv/bin/activate
pip install -e .
python main.py   # first run launches the API configuration wizard

Optional CTF skill pack (pwntools / ROPgadget / ropper + the skills/ctf_* markdown):

pip install -e ".[ctf]"

Global pawn command:

chmod +x pawn.sh && ln -sf "$(pwd)/pawn.sh" ~/.local/bin/pawn

If pawn is not found, run export PATH="$HOME/.local/bin:$PATH" and add that line to your shell profile.

CLI usage:

pawn                              # interactive mode
pawn --eval "your prompt"         # single execution then exit
pawn --eval "prompt" --json       # JSON output (for scripting)

What's New

See CHANGELOG.md for the full version history.

Key Capabilities

Capability	Description
🔀 Dynamic Provider System	Built-in DeepSeek / OpenAI / Anthropic + add any OpenAI-compatible API via /provider
🧠 Persistent Memory	SQLite session history, RAG knowledge base, cross-session full-text search
🛠️ Real Tool Execution	Shell, code sandbox (8 languages), web fetch, file ops, Docker containers
👁️ Vision	Feed screenshots to gpt-4o or claude-sonnet for analysis
📋 Spec-Driven Planning	Agent outputs <plan> XML before every action — no blind execution
💬 Session Management	Tag, search, link, and export conversations with /chat commands
🔐 CTF / Pwn Toolchain	GDB automation, ROP chain building, libc leak resolution, Docker isolation

Supported Models

Provider	Aliases	Best For
DeepSeek	ds-v4-flash ds-v4-pro	Fast default, flagship reasoning
OpenAI	gpt-5.5 gpt-5.4 gpt-5.4-mini gpt-5.4-nano gpt-4o gpt-4.1 o3	Flagship, coding, vision, reasoning
Anthropic	claude-opus claude-sonnet claude-haiku	Frontier reasoning, balanced, fast

Custom providers added via /provider fetch appear automatically in /model and Tab completion.

Provider Management

/provider              # open interactive TUI panel
/provider add <name> <base_url> <ENV_KEY> [anthropic]
/provider fetch <name> # auto-discover models with interactive multi-select
/provider list         # show all providers and key status
/provider test <model> # test connectivity

All keys are stored in ~/.pawnlogic/.env. Provider configs (no keys) go to ~/.pawnlogic/custom_providers.json.

Quick Command Reference

/model [alias]          # switch model
/mode                   # toggle USER / DEV output mode
/chat find <keyword>    # full-text search across all sessions
/think <prompt>         # single deep-reasoning turn
/compact                # summarize + clear context
/undo [n]               # roll back last n turns
/deep                   # switch to deep mode (32k tokens, 50 iter)
/init_project           # initialize GSD engineering pipeline
/pwnenv                 # check CTF toolchain integrity
/keys                   # show API key status for all providers

MCP Tool Integration

cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
# edit mcp_configs.json, add TAVILY_API_KEY= etc. to ~/.pawnlogic/.env
python main.py   # MCP servers load automatically

Supported MCP servers: Tavily (search), Playwright (browser automation), Filesystem (file bridge).

Data Layout

All runtime data and API keys are stored in ~/.pawnlogic/ — never in the project directory.

~/.pawnlogic/
├── .env                    # ALL API keys (LLM providers + MCP tools)
├── custom_providers.json   # user-added provider configs (no keys)
├── mcp_configs.json        # MCP server declarations
├── pawn.db                 # sessions, messages, knowledge base
├── global_skills.md        # GSA skill archive
├── workspace/              # per-session working directories
└── logs/                   # audit logs

The project directory contains no secrets and is safe to commit or share.

Documentation

Document	Description
README.md	This page
README_CN.md	中文版
GUIDE_EN.md	Full reference — commands, architecture, FAQ
GUIDE_CN.md	完整参考手册 — 命令、架构、常见问题
CHANGELOG.md	Version history and release notes
CONTRIBUTING.md	How to contribute, add providers, run tests
SECURITY.md	Vulnerability reporting policy

Support

• GitHub: github.com/john0123412/PawnLogic
• Issues: GitHub Issues for bugs and feature requests