pawnlogic 0.2.1

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

English | Chinese

PawnLogic

PawnLogic is a terminal-first autonomous AI agent with multi-provider model routing, persistent memory, real local tool execution, MCP integration, and a CTF-oriented toolchain. The current public release is 0.2.1.

System Requirements

• Linux or WSL2
• Python 3.10+
• pip
• git only for source checkouts, development, or git-backed skill packs
• ~/.local/bin in PATH when using the global pawn launcher
• Optional: Docker for container tools, browser dependencies for Patchright / Scrapling, and CTF packages for pwn workflows

Quick Start

Option A: install from PyPI

pip install pawnlogic
pawn

The first run opens the API key configuration flow. Runtime files are created under ~/.pawnlogic/, not inside the project directory.

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 PyPI package, and writes ~/.local/bin/pawn.

Option C: source checkout 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

Optional extras:

pip install "pawnlogic[docker]"    # Docker SDK integration
pip install "pawnlogic[browser]"   # Scrapling + Patchright browser tools
pip install "pawnlogic[ctf]"       # pwntools, ROPgadget, ropper
pip install -e ".[dev,ctf]"        # source checkout with tests and CTF tools

pawnlogic[ctf] installs CTF tooling dependencies only. CTF skill packs are optional extension assets that users install explicitly, for example with /sp install <repo_url> into ~/.pawnlogic/skills. Third-party skill packs are not bundled into PyPI distributions unless their upstream license and notices have been reviewed for redistribution. Skill-pack manifests are runtime discovery metadata only; they do not authorize redistribution without a matching THIRD_PARTY_NOTICES.md entry. Git-backed skill-pack installs accept only https://, ssh://, or git@host:owner/repo.git remotes.

Source-checkout launcher fallback:

./pawn.sh

CLI entry points:

pawn
pawn --debug
pawn --eval "summarize this repository"
pawn --eval "summarize this repository" --json
python -m pawnlogic --help

Default pawn uses user-friendly output and hides raw tool-call internals, parser diagnostics, detailed reasoning streams, and low-level API errors. Use pawn --debug or /mode when you need detailed diagnostics.

What's New

Version 0.2.1 is a post-release stabilization patch for the 0.2.0 consolidation architecture:

• Install smoke tests now verify source checkout help entry points, dynamic package version metadata, and the documented pawn console script contract.
• User-friendly CLI mode has regression coverage proving default output hides internals while pawn --debug keeps explicit diagnostics available.
• Provider visibility and stream adapter tests lock DeepSeek/custom-provider visibility rules, public delta dict shape, usage chunks, tool delta ordering, and no-partial stream error behavior.
• Trust-boundary and workspace cleanup tests cover non-interactive fail-closed behavior, trust notices, restore rollback, and staging cleanup reliability.
• Runtime metrics tests verify snapshots are copies, remain local and silent, avoid secret-like failure details, and do not change message persistence shape.
• Release documentation guards now cover README version alignment, SECURITY support rows, translated documentation pairs, language policy, typed-island scope, and wheel skill-pack exclusion.

See CHANGELOG.md for the full release history.

Key Capabilities

Capability	Description
Multi-provider models	Built-in DeepSeek, OpenAI, and Anthropic aliases plus custom OpenAI-compatible or Anthropic-style providers through /provider.
Persistent workspace	SQLite-backed sessions, searchable history, memory commands, knowledge base, per-session workspaces, and audit logs under ~/.pawnlogic/.
Real tool execution	Host shell, code sandbox, file operations, URL fetch, browser automation, Docker containers, and CTF helpers.
Trust-boundary UX	User-mode warnings make it explicit when a tool crosses local host, container, browser, network, delegate, or plaintext HTTP boundaries.
MCP integration	Stdio MCP servers can be configured from ~/.pawnlogic/mcp_configs.json, with roots and stderr logging handled by PawnLogic.
CTF / pwn workflows	Optional pwn tooling, Docker container helpers, GDB automation, ROP chain support, libc leak workflows, and user-installed local skill packs.
Release hygiene	CI runs Ruff, typed-island mypy, and fast Python 3.11 PR checks first, then release/manual validation covers Python 3.10/3.11/3.12, packaging, dynamic E2E, docs structure, language policy, package build, and Trusted Publishing guardrails.

Supported Models

PawnLogic ships with preconfigured model aliases. Only active providers with a configured API key are shown in /model and Tab completion.

Provider	Aliases	Notes
DeepSeek	ds-v4-flash, ds-v4-pro	Default provider; fast primary model plus flagship reasoning model.
OpenAI	gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-4o, gpt-4.1, o3	Coding, vision, multimodal, low-latency, and reasoning aliases.
Anthropic	claude-opus, claude-sonnet, claude-haiku	Opus, Sonnet, and Haiku aliases for Anthropic's Messages API path.

Custom provider model descriptions come from ~/.pawnlogic/custom_providers.json. Re-running /provider update <name> refreshes selected models and writes English fallback descriptions for fetched models when the provider does not supply a useful description.

Provider Management

/provider                         # open the provider TUI
/provider add <name> <base_url> <ENV_KEY> [anthropic]
/provider fetch <name>            # fetch available models and select aliases
/provider update <name>           # re-fetch provider models
/provider activate <name>         # show selected provider models
/provider deactivate <name>       # hide provider models
/provider list                    # show provider and key status
/provider test <model>            # test connectivity for a model alias
/setkey                           # run key setup again
/keys                             # show configured key status

API keys are stored in ~/.pawnlogic/.env. Provider configs, model aliases, and descriptions are stored in ~/.pawnlogic/custom_providers.json without secret values. Provider setup does not write keys into shell startup files.

Plain http:// provider endpoints are allowed for local relays and lab setups, but user-friendly mode prints a trust-boundary warning because requests and API keys are not protected by TLS.

Quick Command Reference

/model [alias]                    # switch model
/mode                             # toggle user-friendly/debug output
/chat find <keyword>              # search all sessions
/think <prompt>                   # run one deeper reasoning turn
/compact                          # summarize and compact context
/undo [n]                         # roll back recent turns
/deep                             # full-power mode
/init_project [desc]              # initialize project state
/pwnenv                           # check CTF toolchain integrity
/ctf init <name>                  # start CTF workspace metadata
/ctf solved [flag]                # mark a confirmed CTF flag as solved
/ctf writeup                      # export a CTF writeup draft
/sp install <repo_url>            # install a git-backed skill pack

Run /help inside PawnLogic for the full command list.

Trust Boundary

PawnLogic is an agent execution tool, not a security sandbox. It intentionally executes real tools with the current user's permissions when you ask it to do so. Pattern filters, Docker boundaries, and capability profiles reduce accidents; they do not contain a determined attacker.

User-friendly mode prints explicit trust-boundary notices for host shell execution, Docker container exec, browser/network-capable tools, private network URL access, delegated sub-agents, and plaintext HTTP providers. Use pawn --debug when you need lower-level tool arguments and diagnostics. Docker file mounts are workspace-bound by default, including read-only mounts; outside read-only challenge files require explicit allow_host_read_mount.

Host shell execution now passes through an operation policy before subprocess startup. Low-risk commands run normally, medium-risk commands are classified for audit, high-risk commands require explicit interactive confirmation, and critical operations are denied by default. Non-interactive execution, including pawn --eval, fails closed when a high-risk command would require confirmation. DANGEROUS_PATTERNS remains only one misuse/risk classifier; it is not a sandbox boundary and cannot stop a malicious local user.

MCP Tool Integration

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

pawn
cp ~/.pawnlogic/mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
# edit ~/.pawnlogic/mcp_configs.json and add keys with /setkey or ~/.pawnlogic/.env
pawn

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

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

Supported example MCP servers include Tavily search, Playwright browser automation, and a filesystem bridge. External fetch MCP is disabled in the example because uvx mcp-server-fetch may contact PyPI during startup; use PawnLogic's built-in fetch_url unless you explicitly enable that MCP server.

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

Data Layout

All runtime data and API keys are stored in ~/.pawnlogic/.

~/.pawnlogic/
├── .env                    # API keys
├── custom_providers.json   # user 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_zh-CN.md	Chinese README
GUIDE.md	Full reference: commands, architecture, and FAQ
GUIDE_zh-CN.md	Chinese full reference
CHANGELOG.md	Version history and release notes
CONTRIBUTING.md	Contribution, provider, and test workflow
SECURITY.md	Vulnerability reporting policy
THIRD_PARTY_NOTICES.md	Third-party attribution and redistribution notes

Support

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