English | 中文

Personal all-in-one pi coding toolkit for agentic coding workflows.

Combines subagents, web research, document conversion, LSP code intelligence, automatic diagnostics hooks, developer commands, and lightweight workflow reminders into a single modular pi extension.

pi install devkit-pi

npm package: https://www.npmjs.com/package/devkit-pi

• Node.js >=22.19.0

{
 "pi": {
 "extensions": ["./index.ts"]
 }
}

git clone https://github.com/0xnayuta/devkit-pi.git
cd devkit-pi
pnpm install
pnpm test

All agents are readonly by default. The main agent is the sole orchestrator — subagents cannot spawn other subagents.

Writable custom subagents are experimental. The default and recommended mode is readonly; subagents.allowWrite=true does not provide a complete sandbox, audit trail, or rollback guarantee. See Subagents reference and Security model.

Place markdown files in .pi/agents/ (project) or ~/.pi/agent/agents/ (user):

---
name: custom-reviewer
description: Project-specific reviewer
readonly: true
tools: read, grep, find, ls
---
You are a custom review subagent.

subagent({ agent: "explorer", task: "Find authentication code" })

Delegates a focused task to a specialized agent. Results are sanitized and returned to the parent agent.

convert_content({ path: "docs/spec.pdf" })
convert_content({ url: "https://example.com/report.docx" })

Converts a local file or a safely downloaded remote HTTP(S) file to Markdown. The first provider is the optional external MarkItDown CLI (markitdown); install and configure it separately when needed. Local paths are restricted to the active workspace, remote downloads enforce private-network protection by default, and output is truncated according to convertContent.maxContentChars.

Exposes language server capabilities: definition, references, hover, signature, symbols, diagnostics, workspace-diagnostics, servers.

Mutating actions (rename, codeAction, restart) are disabled by default and always blocked in subagent processes.

Automatically runs LSP diagnostics after each agent turn (configurable: agent_end | edit_write | disabled).

The /toolkit command provides diagnostic and inspection subcommands:

Config file: ~/.pi/agent/extensions/devkit-pi/config.json.

Each module can be independently enabled or disabled. See Configuration reference for the canonical defaults and normalize rules.

INVALID_INPUT | SUBAGENTS_DISABLED | UNKNOWN_AGENT | SUBAGENT_DISABLED | SUBAGENT_DEPTH_EXCEEDED | SUBAGENT_TIMEOUT | SUBAGENT_FAILED | SUBAGENT_OUTPUT_TRUNCATED

Web tools return structured errors with error.code and error.message. Common codes include INVALID_INPUT, WEB_SEARCH_INVALID_QUERY, WEB_SEARCH_FAILED, WEB_SEARCH_TIMEOUT, PROVIDER_AUTH_FAILED, PROVIDER_RATE_LIMITED, PROVIDER_UNAVAILABLE, NETWORK_ERROR, CONTENT_FETCH_INVALID_URL, CONTENT_FETCH_FAILED, CONTENT_FETCH_TIMEOUT, and NOT_FOUND.

See the canonical list in Web tools error codes.

convert_content returns structured errors with error.code and error.message. Common codes include INVALID_INPUT, FILE_NOT_FOUND, FILE_TOO_LARGE, UNSUPPORTED_PROTOCOL, COMMAND_NOT_FOUND, CONVERT_TIMEOUT, CONVERT_FAILED, NETWORK_ERROR, and PRIVATE_NETWORK_BLOCKED.

See Convert content tool reference.

src/
├─ index.ts # Thin entry point — registers all modules
├─ modules/
│ ├─ subagents/ # Task delegation, agent discovery, execution
│ │ └─ commands/ # doctor, list, logs formatting
│ ├─ web/ # Search, fetch, content extraction, caching
│ │ └─ providers/ # ddgs, brave, tavily, serper, openserp, searxng
│ ├─ convert/ # convert_content tool, MarkItDown provider, safe downloads
│ ├─ lsp/ # LSP tool, diagnostics hook, server management
│ ├─ commands/ # Unified /toolkit command registration
│ └─ guards/ # Git context, first-write, verification workflow reminders
├─ config/ # Configuration loading and defaults
└─ shared/ # Types, error codes, utilities
index.ts # Package root entry, re-exports src/index.ts
agents/ # 5 built-in agent definitions (markdown)
tests/ # Module tests plus shared, commands, guards, manifest, fixtures
docs/ # User-facing guides/reference and zh mirror
internal-docs/ # Maintainer docs: audit, ADRs, planning, issues, archive

1. The main agent is the sole orchestrator
2. Subagents cannot spawn other subagents (maxDepth = 1)
3. Default readonly — write capability requires explicit configuration and remains experimental for custom subagents
4. LSP mutating actions (rename, codeAction, restart) are disabled by default and always blocked in subagent processes
5. convert_content uses an optional external MarkItDown CLI provider; heavy document conversion dependencies are not bundled into the core package
6. Guards are lightweight reminders only; they do not enforce hard workflow gates
7. Each module can be independently enabled or disabled

pnpm typecheck # Type check
pnpm lint # Lint with Biome
pnpm lint:fix # Auto-fix lint issues
pnpm format # Format with Biome
pnpm test # Run unit tests
pnpm test:coverage # Generate lightweight V8 coverage visibility reports
pnpm docs:check # Validate documentation

Online documentation site: https://devkit-pi.wangyan.life/

npm package: https://www.npmjs.com/package/devkit-pi

The VitePress documentation site can be previewed locally:

pnpm docs:dev
pnpm docs:build
pnpm docs:preview

• Documentation index
• Reference index
• Goals and scope
• Security model
• Configuration reference
• Subagents reference
• Subagent tool reference
• Agent definition
• Result schema
• Toolkit commands reference
• LSP tools reference
• Web tools reference
• Convert content tool reference
• Web providers reference
• Web tools error codes
• Internal maintainer docs

MIT © Izayoi Nayuta