Why Chalin

Chalin is a Pi Coding Agent extension for work that benefits from deliberate coordination: broad repository analysis, risky edits, multi-step implementation, memory recall, and review-heavy workflows.

The extension keeps small prompts direct. When a task needs more structure, Chalin gives the primary Pi agent a guarded way to route work through focused subagents, preserve handoffs, use memory, and surface what is happening in the TUI.

The product goal is simple: keep the human in command while giving complex engineering work a reliable execution frame.

Features

| Area | Capability | | --- | --- | | Routing | Direct execution for bounded work; routed workflows for broad, risky, or memory-sensitive work. | | Subagents | Built-in scout, planner, worker, reviewer, researcher, delegate, oracle, context-builder, and conflict-resolver agents. | | Workflow shapes | single, chain, parallel, dag, and memory-only plans. | | Memory | Built-in SQLite memory with review, or native Engram memory with optional cloud sync. | | Safety | Approval thresholds, critical-route blocking, recursion guards, single-writer protection, mutation expectation checks, and destructive-action confirmation. | | State | Resumable runs, artifacts, validation contracts, activity monitoring, and cached discovery context. | | TUI | Smart Panel, Settings, Agent Manager, Memory Review, Activity, Artifacts, and WebFetch audit panels. |

Quick Start

Requirements

• Bun >=1.3.14
• Pi Coding Agent runtime

Install

pi install npm:pi-chalin

For local development in this repository:

bun install

Load In Pi

pi-chalin is exposed as a Pi extension through package.json:

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

Once Pi loads the package, use /chalin inside a Pi session.

Commands

| Command | Purpose | | --- | --- | | /chalin | Open the Smart Panel. | | /chalin on | Enable autonomous routing for the current project. | | /chalin off | Disable autonomous routing for the current project. | | /chalin settings | Tune routing, safety approvals, memory provider, agent overrides, maintenance, and diagnostics. | | /chalin agents | Inspect agents and override model or thinking settings. | | /chalin memory | Review built-in memory records or Engram observations. | | /chalin memory <query> | Search the configured memory backend. | | /chalin artifacts | Open resumable task artifacts. | | /chalin artifacts <feature> | Resume context for a named feature artifact. | | /chalin activity | Inspect the active or latest run. | | /chalin web | Review cached WebFetch bundles and freshness. | | /chalin status | Print routing, autonomy, safety, memory, agent, and guard status. |

Tools

The extension registers Pi tools for the primary agent. The primary agent stays in control; Chalin provides the execution frame when routing is useful.

| Tool | Purpose | | --- | --- | | chalin_route | Run a selected workflow with concrete agents, topology, risk, memory, and artifact needs. | | chalin_resume | Resume the latest paused or stale Chalin run. | | chalin_interview | Ask blocking clarification questions before planning or execution. | | chalin_memory_search | Retrieve compact durable memory during direct or routed work. | | chalin_memory_write | Save durable project or user knowledge through WriteGuard. | | chalin_memory_revise | Correct stale or inaccurate memory with evidence. | | chalin_artifact_resume | Load resumable task context from stored artifacts. | | chalin_web_search | Search or fetch current web context through the audited web layer. |

Child agents receive only the guarded tools appropriate to their role, capability set, and budget.

Configuration

Project configuration lives at:

.pi-chalin/config.json

User-level configuration and agents live under:

~/.pi/chalin/

Useful top-level settings:

{
  "enabled": true,
  "autonomy": "balanced",
  "safety": {
    "approvalRiskThreshold": "medium"
  },
  "memory": {
    "provider": "auto"
  }
}

Use /chalin settings for the supported interactive path. It exposes:

• routing on/off and autonomy;
• safety approval threshold, including a no-prompt mode for non-critical routes;
• memory provider selection;
• agent override summary and Agent Manager access;
• maintenance for caches;
• diagnostics.

Critical routes remain blocked by the safety policy even when approval prompts are disabled.

Memory

Chalin supports three memory modes:

| Provider | Behavior | | --- | --- | | auto | Uses Engram when reachable, otherwise falls back to built-in memory. | | engram | Uses Engram as the source of truth for memory surfaces and tools. | | pi-chalin | Uses the built-in SQLite memory store. The UI labels this mode as built-in. |

Built-in memory keeps the review workflow: pending candidates can be approved, rejected, revised, or deleted. Destructive memory actions require confirmation.

Engram mode uses Engram directly for memory listing, search, write, revise, and routed workflow context. When the configured Engram runtime is local and autoSync is enabled, Chalin can use Engram's local-first cloud sync path through the runtime environment.

Common Engram environment variables:

ENGRAM_URL
ENGRAM_PORT
ENGRAM_BIN
ENGRAM_CLOUD_TOKEN
PI_CHALIN_MEMORY_PROVIDER

Agents

Agents are Markdown files with YAML frontmatter. They can come from three scopes:

agents/*.md                built-in package agents
.pi-chalin/agents/*.md     project agents
~/.pi/chalin/agents/*.md   user agents

Resolution order:

name             -> project/name, then user/name, then built-in/name
project/name     -> project only
user/name        -> user only
built-in/name    -> built-in only

Project agents win locally, user agents remain portable, and built-ins provide the default catalog.

Architecture

Chalin is a modular monolith. The extension keeps runtime boundaries explicit without splitting the product into premature services.

src/index.ts              extension registration
src/commands.ts           /chalin command tree
src/tools.ts              Pi tool definitions
src/autoroute.ts          prompt-time routing guidance
src/kernel.ts             route validation and orchestration
src/runner.ts             worker execution, resume, and run metrics
src/agents.ts             agent catalog and resolution
src/config.ts             config, safety, autonomy, and overrides
src/memory.ts             built-in memory store
src/memory-provider.ts    built-in and Engram memory backends
src/artifacts.ts          resumable task state and handoffs
src/webfetch.ts           audited external context cache
src/worktrees.ts          isolated writer worktrees
src/ui.ts                 TUI panels and confirmations
src/schemas.ts            shared runtime types

Runtime state is project-local:

.pi-chalin/config.json
.pi-chalin/agents/
.pi-chalin/artifacts/
.pi-chalin/cache/
.pi-chalin/memory.sqlite
.pi-chalin/runs/

Development

Fast verification:

bun run typecheck
bun run test

Focused evaluator scripts are available for routing, memory, trace, trajectory, and workflow quality work:

bun run eval
bun run eval:memory
bun run eval:trace
bun run eval:workflow

Use the broader evaluator path when changing routing policy, runner behavior, child-tool budgets, memory semantics, or workflow scoring.

Design Principles

• Route only when routing improves quality.
• Keep the human in command.
• Make autonomy observable.
• Prefer durable memory with review.
• Treat safety gates as product behavior.
• Verify behavior with tests and evaluators.

License

Chalin is distributed under an MIT-style license with an attribution addendum. See LICENSE.