Pi Agent

@shelson/pi-agentv2026.09.26.2· 11d agoMODELS

01README

Run the pi coding agent from swamp workflows via its in-process TypeScript SDK — no subprocess, no terminal scraping.

Each run sends one prompt to a pi agent session and captures the response text, tool calls, token usage, and cost as structured swamp data. Sessions are pi's persistent JSONL sessions, so successive runs with the same sessionKey continue the same conversation; give each work item its own key to isolate context.

The agent is hermetic: provider, model, and an explicit API key (usually sourced from a vault with vault.get(...)) are required, and the running user's ~/.pi is never read or written. Credentials, global resources, and sessions live in an isolated repo-local agentDir, so the agent starts clean and loads only project resources from its working directory. Working directory, thinking level, tool allow/deny lists, resource discovery, and the system prompt are all model configuration. A models method lists the models your credentials can reach, and sessions lists pi sessions for a directory.

02Models1

@shelson/pi-agentv2026.09.26.2pi_agent.ts

Global Arguments

Argument	Type	Required	Description
cwd	string	yes	Working directory for the agent's tools and project resource discovery. Relative paths resolve against the swamp repo directory.
provider	string	yes	Provider id, e.g. "openrouter" or "anthropic".
model	string	yes	Model id within the provider, e.g. "deepseek/deepseek-v4.1-flash".
apiKey	string	yes	Provider API key (sensitive). Pass it via --global-arg from a vault, e.g. a vault.get("my-vault", "OPENROUTER_API_KEY") expression.
agentDir?	string	no	Isolated pi config dir (auth, models store, global resources). Defaults to <repo>/.swamp/pi-agent/<instance>. The user's ~/.pi is never read or written.
modelsPath?	string	no	Explicit models.json for custom model definitions. Omit to disable custom models entirely (the global models.json is never read).
tools?	array	no	Allowlist of tool names. Omit to use pi's defaults (read, bash, edit, write) plus extension tools.
excludeTools?	array	no	Tool names to disable after the allowlist applies.
noTools?	enum	no	"all" starts with no tools; "builtin" drops read/bash/edit/write but keeps extension tools.
noExtensions	boolean	yes	Skip discovering pi extensions from the working directory. Global extensions are never loaded.
noSkills	boolean	yes
noPromptTemplates	boolean	yes
contextFiles	enum	yes	AGENTS.md / CLAUDE.md context files to load: "cwd" (working directory only, default), "ancestors" (walk parent dirs like pi does), or "off".
skills	array	yes	Extra skill paths — a directory containing SKILL.md, or a single .md skill file — loaded in addition to cwd discovery. Relative paths resolve against the swamp repo dir.
systemPrompt?	string	no	Replace the default system prompt entirely.
appendSystemPrompt	array	yes	Extra system-prompt sections appended after the default.
sessionDir?	string	no	Directory for persistent session files. Defaults to <agentDir>/sessions.
persistSessions	boolean	yes	Persist sessions to disk. Set false for throwaway in-memory conversations.
defaultTimeoutMs	number	yes	Abort a run that exceeds this wall-clock budget.

fn run(prompt: string, sessionKey: string, sessionFile?: string, newSession: boolean, cwd?: string, model?: string, tools?: array, excludeTools?: array, systemPrompt?: string, timeoutMs?: number)

Launch or continue a pi agent session, send one prompt, and capture the response, tool calls, tokens, and cost

Argument	Type	Required	Description
prompt	string	yes	The message to send to the agent
sessionKey	string	yes	Conversation identity; the same key continues the same session. Use one key per work item to isolate context.
sessionFile?	string	no	Explicit pi session file to continue, overriding the stored session for this key.
newSession	boolean	yes	Ignore any stored session and start a fresh conversation.
cwd?	string	no	Working directory override for this run.
model?	string	no	Model id override within the instance's provider.
tools?	array	no
excludeTools?	array	no
systemPrompt?	string	no	System prompt override for this run.
timeoutMs?	number	no	Abort the run after this many milliseconds.

fn models()

List models available with the configured credentials (aids model selection)

fn sessions(cwd?: string, limit: number)

List persisted pi sessions for a working directory

Argument	Type	Required	Description
cwd?	string	no
limit	number	yes

Resources

session(infinite)— Persisted conversation summary for one session key

run(infinite)— One prompt/response turn with its usage

catalog(infinite)— Models available with the configured credentials

sessionList(infinite)— Discovered pi sessions for a working directory

03Previous Versions1

2026.09.26.1Sep 26, 2026

04Stats

100 / 100

Downloads

Archive size

2.4 MB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/shelson/swamp-extensions

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#agent #pi #coding-agent #automation