pi-dent-agent

A generic coding agent as a pi extension: Bash, Task, Agent, Fleet, Script, Search, Markdown and more tools, with billing and terms extensions bundled

Packages

Package details

extension

Install pi-dent-agent from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-dent-agent
Package
pi-dent-agent
Version
0.2.16
Published
Nov 22, 2026
Downloads
2,930/mo · 2,930/wk
Author
dralban68
License
MIT
Types
extension
Size
116.2 MB
Dependencies
20 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts",
    "./node_modules/pi-dent-purse/index.ts",
    "./node_modules/pi-dent-terms/index.ts",
    "./node_modules/pi-mcp-adapter/index.ts",
    "./node_modules/pi-anthropic-oauth/src/index.ts",
    "./node_modules/pi-web-access/dist/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-dent

A generic coding agent, built as a pi extension: it registers the Bash, Task, Agent, Fleet, Script, Plugin, Skill, Session, Schedule, Search, Markdown, and AskUserQuestion tools and the tasks, fleet, and dent slash commands, replaces the host's built-in bash tool, and adds the task browser. Specifications live in specs/; the formal source of truth for every behavior.

Requires pi 1.5.2 or later and Node 26.

Core concepts

How the terms relate is mapped in docs/concepts.md; the specs decide.

Concept What it is Spec
Task One supervised Agent, Script or Bash run. In the foreground the tool call returns the result; in the background it returns a task ID at once and a completion notification follows. Task reads, waits for or kills one; the task browser (shift+right) shows the whole task tree. task.md
Dispatch One Agent call. It runs a child session: in-process, with its own context and session file, returning only its final answer. A static dispatch takes its prompt from an agent definition, a dynamic dispatch from the call. resume continues a retained child session file in place. agent-tool.md
Child session Gets a subset of the dispatching session's tools (the tool cap), the extensions behind them, and the providers the dispatching session's extensions registered, so it can run on any model that session can. agent-tool.md, Sections 3 and 4.2
Agent definition A Markdown file in an agents/ folder or a plugin: a name, an optional description and model, and a body that becomes the child's system prompt. agent.md
Model string provider/model-id[:thinking], or a model class from modelClasses such as fast:high. model-string.md
Model guidance Which model to use when. It forms the model catalog in the Agent description, restricts dispatches to guided models, and carries billing annotations (quota, price) that Session also reports. model-guidance.md, billing.md
Skill A SKILL.md of instructions the model loads with Skill when a task matches its description. skill.md
Plugin A directory, under its namespace, of commands, agent definitions, skills, scripts for Script, and a context appended to system prompts. Plugin reads its files. plugin.md
Fleet The main sessions on this machine, registered in the local session store. Fleet lists them and sends or queries across them; Schedule messages the same session later. fleet-tool.md, schedule-tool.md
Session tree A session file and the session files of its child sessions. Search finds and reads its transcript items, through the session index. search-tool.md
Boot snapshot The configuration and the agent, skill and plugin catalogs, read once at start or /reload and fixed until the next. config-file.md

Configure pi

Install the package from npm:

pi install npm:pi-dent-agent   # add it to pi's packages
pi -e npm:pi-dent-agent        # or try it for one run

For development, install its dependencies once (needs pnpm), then list the checkout in pi's settings:

pnpm install   # in this repository

~/.pi/agent/settings.json:

{
  "packages": ["../../src/pi-dent-agent"]
}

Paths in a user-scope packages list resolve against ~/.pi/agent, so ../../src/pi-dent-agent is ~/src/pi-dent-agent; entries in a project's .pi/settings.json resolve against that .pi directory. pi install <source> and pi remove <source> write this list for you; pi list shows it, and pi config enables or disables the resources a package declares.

Listing the package is the whole installation. It loads pi-dent and its bundled extensions, each as its own extension: pi-dent-purse (the billing service), pi-dent-terms (the Terms tool), pi-mcp-adapter, pi-anthropic-oauth, and pi-web-access, per specs/package.md. Those extensions come from this package, so they must not also appear in packages — a second copy loads twice and its tools collide. Update them with pnpm update in this repository; pi update covers pi packages, not bundled dependencies.

Settings, packages, and configuration are read at boot: restart pi, or run /reload, after changing any of them.

For development inside this repository, pi -ne -e ./ loads only what package.json → pi.extensions lists (docs/development.md).

Configure pi-dent in pi

pi-dent.conf is a JSONC file read from at most two layers, the global one and the project one in pi's working directory:

Order Layer Path
1 (base) global ~/.pi/pi-dent/pi-dent.conf
2 (priority) project <cwd>/.pi/pi-dent/pi-dent.conf

Both layers merge deeply and the project layer wins every conflict, so machine-wide models and guidance go in the global file and repository-specific agents, plugins, and tooling go in the project one. A missing file contributes nothing, silently. A complete annotated sample with every root key is in docs/pi-dent-conf.md.

The root keys:

Key Purpose Spec
modelClasses Named classes usable inside any model string, e.g. "fast:low" model-string.md
modelGuidance Which model to use when (the Agent description), plus guidance rules model-guidance.md
agentLiveness idleTimeoutMs and absoluteTimeoutMs bounding child dispatches agent-tool.md
agents Prompt overrides for entries of the agent catalog agent.md
plugins Plugin directories by entry key; the namespace is the manifest name plugin.md
taskBrowser shortcut, the task browser key, default shift+right task-browser.md

~/.pi/pi-dent/pi-dent.conf:

{
  // Classes usable in any model string: "fast", "fast:high", ...
  "modelClasses": {
    "fast": "deepseek/deepseek-flash",
    "review": "tl/claude-opus-5-5:high",
  },
  "modelGuidance": {
    "models": {
      "deepseek/deepseek-flash": { "when": "implementation" },
    },
    "rules": [{ "match": "flash", "rule": "verify its output before relying on it" }],
  },
  "agentLiveness": { "idleTimeoutMs": 600000, "absoluteTimeoutMs": 3600000 },
}

A modelGuidance.models key is a concrete provider/model-id, never a class name. Its when texts form the model catalog in the Agent tool description; the guidance message carries only the billing annotations of the guided models, and the rules of matching sessions.

<repo>/.pi/pi-dent/pi-dent.conf adds what only that repository needs; plugins paths resolve against the layer directory, so this one is <repo>/.pi/pi-dent/tools/site, and agents keys must name entries of the agent catalog:

{
  "agents": { "reviewer": { "prompt": "Review the change and report only real defects." } },
  "plugins": { "site": { "path": "./tools/site" } },
  "taskBrowser": { "shortcut": "ctrl+t" },
}

String values may use ${env.NAME} for an environment variable and ${project.root} for pi's working directory; $$ writes a literal $. An undefined variable is a diagnostic, never an empty string.

An unknown root key, an unreadable file, or a malformed value produces one pi-dent: … notification at start and is ignored; the rest of the configuration still applies. Configuration changes take effect at the next boot or /reload, never mid-window.

A layer directory also holds its agents/ and skills/ folders: ~/.pi/pi-dent/agents/, <repo>/.pi/pi-dent/skills/<name>/SKILL.md, and so on. Agent definitions, skills, plugins, and every configuration field are specified under specs/.