pawnlogic 0.1.0

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

English | Chinese

🤖 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
• git only for source checkout or development
• ~/.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 — one-line installer

curl -fsSL https://raw.githubusercontent.com/john0123412/PawnLogic/main/install.sh | bash
pawn

The installer creates an isolated venv under ~/.local/share/pawnlogic, installs the official pawnlogic package with pip, and writes a ~/.local/bin/pawn launcher. It does not copy the source tree or store runtime data in the project.

Option C — from source for development

git clone https://github.com/john0123412/PawnLogic.git && cd PawnLogic
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pawn             # first run launches the API configuration wizard

Optional CTF tooling (pwntools / ROPgadget / ropper):

pip install "pawnlogic[ctf]"       # package install
pip install -e ".[ctf]"            # source checkout

PyPI and curl installations do not include local skills/ packs. Use a source checkout or /sp install <repo_url> when you want repository-backed skill packs.

Source-checkout launcher fallback:

./pawn.sh

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

CLI usage:

pawn                              # interactive user-friendly mode
pawn --debug                      # interactive mode with detailed diagnostics
pawn --eval "your prompt"         # single execution then exit
pawn --eval "prompt" --json       # JSON output (for scripting)

Default pawn hides raw tool-call arguments, parser diagnostics, and reasoning streams. Use pawn --debug when you need detailed terminal logs, tool-call visibility, API error details, and parser diagnostics. In an interactive session, /mode toggles between the same user-friendly and debug output modes.

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

DeepSeek is active by default. Custom providers appear in /model and Tab completion only after their key is configured, models are fetched, and the provider is activated. Descriptions shown by /model come from ~/.pawnlogic/custom_providers.json for custom providers. Re-running /provider update <name> refreshes selected models from the provider and writes English fallback descriptions for fetched models.

Provider Management

/provider              # open interactive TUI panel
/provider add <name> <base_url> <ENV_KEY> [anthropic]
/provider fetch <name> # fetch available models and select interactively
/provider update <name>
/provider activate <name>
/provider deactivate <name>
/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, showing active configured providers
/mode                   # toggle user-friendly/debug output
/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

For pip or one-line installer users, PawnLogic creates editable templates in ~/.pawnlogic/ on startup:

pawn   # creates ~/.pawnlogic/env.example and ~/.pawnlogic/mcp_configs.example.json
cp ~/.pawnlogic/mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
# edit ~/.pawnlogic/mcp_configs.json, add TAVILY_API_KEY= etc. with /setkey or ~/.pawnlogic/.env
pawn   # MCP servers load automatically when mcp_configs.json exists

For source checkout users, the repository template can also be copied directly:

cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json

Supported MCP servers: Tavily (search), Playwright (browser automation), Filesystem (file bridge). The example keeps the external fetch MCP disabled by default because uvx mcp-server-fetch may contact PyPI during startup. Use PawnLogic's built-in fetch_url unless you explicitly enable that MCP server and allow network installation.

MCP subprocess stderr is written to ~/.pawnlogic/logs/mcp/<server>.stderr.log by default so server startup banners do not pollute the main terminal. Set top-level "debug_stderr": true in mcp_configs.json when you want raw MCP stderr on the console for troubleshooting. PawnLogic also advertises MCP roots for the current working directory and ~/.pawnlogic/workspace.

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
├── skills/                 # optional user-installed skill packs
├── 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	Chinese README
GUIDE_EN.md	Full reference — commands, architecture, FAQ
GUIDE_CN.md	Chinese complete reference
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