pbi-agent is a token-efficient local coding agent designed to cut session token usage by up to 60% while keeping the model focused on the task. Its main interface is the browser-based web UI, and it also offers a non-interactive CLI mode for scripted or terminal-first runs. It combines interactive sessions, reusable project skills and commands, sub-agents, MCP tools, and kanban-style coordination in one workspace-first runtime.
Repository: https://github.com/pbi-agent/pbi-agent
Full documentation lives at pbi-agent.github.io/pbi-agent.
Three pillars
Modern LLMs are more intuitive and capable, so a coding agent does not need to over-script every step. pbi-agent is built around three concise defaults that let the model choose the trajectory while the runtime protects the context window.
-
Compact default system instructions The default prompt is intentionally small: define the goal, active tools, and hard workspace rules, then let the model reason from the task. Users can still add
INSTRUCTIONS.md,AGENTS.md, skills, commands, and sub-agents when a project needs more guidance. -
Bounded workspace output Shell output is returned raw with size guardrails, while workspace search, read, and list operations use
codetool-exploreto return compact, model-ready file evidence. The agent avoids dumping unbounded terminal logs or whole files when snippets are enough. -
Tool history omitted by default When resuming a session,
pbi-agentkeeps the conversation useful without replaying every prior tool call and result by default. This supports isolated flows such as planning, review, or fresh task runs. If previous tool traces matter, enable them with--include-tool-historyor the web UI tool-history toggle.
Together, these defaults are designed to reduce session token usage by up to 60%, with larger savings possible in long multi-turn sessions where tool output and history would otherwise dominate the context.
Quick Start
- Install the CLI:
uv tool install pbi-agent
- Open your project workspace:
cd /path/to/my-project
- Start the app:
pbi-agent
Running pbi-agent with no command launches the browser UI on http://localhost:8000.
Docs
Customization
pbi-agent supports a few workspace-level customization points:
INSTRUCTIONS.mdreplaces the default system prompt for the workspace.AGENTS.mdadds project-specific rules on top of the active prompt..agents/skills/<skill-name>/SKILL.mdadds project-local skills that are advertised to the model..agents/agents/<agent-name>.mdadds project-local sub-agents that can be selected through thesub_agenttool..agents/mcp.jsondeclares MCP servers whose tools are exposed to the model at startup.
See the full Customization guide for examples and behavior details.
Common Commands
pbi-agent
pbi-agent web
pbi-agent run --prompt "Summarize this repository."
pbi-agent skills add
pbi-agent skills add --skill openai-docs
pbi-agent commands add
pbi-agent commands add --command execute
pbi-agent agents add
pbi-agent agents add --agent code-reviewer
1 maintainer
Release files for pbi-agent 0.34.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pbi_agent-0.34.0.tar.gz | 82.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pbi_agent-0.34.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 86.9 MB
Release files / pbi_agent-0.34.0.tar.gz
| Download URL | pbi_agent-0.34.0.tar.gz |
|---|---|
| Size | 82.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69c7488ffa4d99a86e3d2759449bba035074abee4d83eaf2ebe1446e9d51f403
|
|
BLAKE2b-256 checksum How to use checksums |
f9414ed243bf8522524d2aefe1ad10e7f8dbb897bcb9b289fa2db913cff07b4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / pbi_agent-0.34.0-py3-none-any.whl
| Download URL | pbi_agent-0.34.0-py3-none-any.whl |
|---|---|
| Size | 4.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6104d145b0af0d4fe2142afa7f5ae50ecfd7765fdad07c055d29f2cf7dc3f8d
|
|
BLAKE2b-256 checksum How to use checksums |
cfe4362a1c07eec3f5f10ec2d6ff65333daf6a4da5fa00c45170edc21bf1380f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
