pie-lab
A local-first agent lab that starts from pi, adds 9router operations, ports Hermes-style learning, and connects agents to web chat, Telegram, and Discord.

pielab.ai · install.sh · docs · chat guide · learning loop

pie-lab is a practical fork-and-integration project for building a personalized Agentic Development Kit.

It starts from the full pi coding-agent source tree, then brings in the most useful operational ideas from 9router, the chat bridge experience from pi-chat, and the learning-loop pattern from hermes-agent.

The operations dashboard inspired by 9router and the chat experience inspired by pi-chat have both been rebuilt as Next.js apps inside this repository, so they can work directly with pie-lab's local server, router, provider settings, and agent bridge.

The result is a single local-first workspace where the CLI agent, model router, provider/account operations, dashboard, persistent memory, automatic skills, and external chat bridges are meant to work together.

Pio is pie-lab's AI Ant Companion.

Imported baseline details are tracked in docs/origins.md.

• pie coding-agent CLI based on the original pi workflow.
• Local OpenAI-compatible API server at apps/server.
• Next.js dashboard at apps/dashboard for usage, cost, providers, quota, routing policy, proxy, media tests, logs, and Learning Loop operations.
• Pie Chat web UI at apps/chat.
• Telegram/Discord bridge extension with /chat-config, /chat-connect, /chat-spawn-all, and /chat-workers.
• pie gateway for long-running Telegram/Discord messaging plus scheduled cron delivery without keeping a TUI session open.
• 9router-style model routing with aliases such as auto:coding, auto:chat, auto:learning, and auto:memory.
• Provider connection storage, account selection, fallback attempts, quota-aware routing, cooldown/model lock handling, and usage/cost records.
• Claude Code local provider path through claude-code-adk.
• Hermes-style Learning Loop:
  • local memory in ~/.pie/agent/memories
  • global agent skills in ~/.pie/agent/skills
  • project skills in .pie/skills
  • background review and proposal records
  • skill curator archive/restore + LLM-driven consolidation (umbrella skill merging)
• Scheduler (pie cron):
  • IANA timezone-aware cron expressions (0 9 * * * in Asia/Seoul)
  • Grace window + missed-run fast-forward (skips stale jobs, not re-runs them)
  • Wake-gate: script last line {"wakeAgent":false} skips LLM call
  • Separate script/agent timeouts (scriptTimeoutSeconds + timeoutSeconds)
  • [SILENT] response prefix → skip delivery
  • Stale running job cleanup on startup
• Gateway periodic nudge: per-channel nudgeIntervalMinutes triggers proactive agent turns on inactivity

• Node.js >=22.19.0 is required. Older Node 22 builds such as 22.12.0 can fail during npm run build.
• npm
• Git
• tmux only if you use the older /chat-spawn-all worker mode. pie gateway does not require tmux.
• At least one model provider credential or local provider path

The repository includes .node-version, so with nvm:

nvm install
nvm use
node -v

Make sure node -v prints v22.19.0 or newer before running npm install or npm run build.

The default user install is the npm package, bootstrapped by the GitHub Pages installer:

curl -fsSL https://jikime.github.io/pie-lab/install.sh | sh
pie

The installer checks for Node.js >=22.19.0, checks for npm, then installs:

npm install -g --ignore-scripts @pie-lab/coding-agent

For inspection-first installs, download the script before running it:

curl -fsSLO https://jikime.github.io/pie-lab/install.sh
sh install.sh

git clone git@github.com:jikime/pie-lab.git
cd pie-lab
nvm install
nvm use
node -v
npm install
npm run build

npm run build builds the core packages, server, dashboard, and Pie Chat. The Pie Chat build also type-checks the Telegram/Discord bridge.

For day-to-day local CLI development, run the source CLI directly:

./pie-test.sh

To make the local checkout available as a pie command on your PATH, build first and then link the workspace package:

npm run build
npm link --workspace @pie-lab/coding-agent
pie

You can also install the published CLI package directly:

npm install -g --ignore-scripts @pie-lab/coding-agent
pie

For this repository, the source checkout is the recommended path because the dashboard, server, chat bridge, and Learning Loop changes live together.

You need at least one usable provider before the agent or API server can answer model requests.

Common options:

• Use the CLI /login flow inside pie.
• Add provider connections from the dashboard Providers page.
• Export API keys such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, or other provider-specific variables supported by packages/ai.
• Use claude-code-adk/* models when you want the local Claude Code login/subscription path instead of Anthropic API keys.

Provider connection and usage state is stored under:

~/.pie/agent/

CLI and server usage records share ~/.pie/agent/usage.jsonl by default. Set PIE_LAB_USAGE_PATH when you want the dashboard/server to read a different usage file.

You can start the main development stack with:

npm run dev

Before starting, this command clears pie-lab's fixed development ports 4873, 4876, and 4877 so stale server, dashboard, or chat processes do not cause EADDRINUSE errors. To skip that cleanup, run npm run dev:start instead or set PIE_DEV_SKIP_PORT_CLEANUP=1.

That starts package watchers plus:

You can also run each app separately:

npm --workspace @pie-lab/server run dev
npm --workspace @pie-lab/dashboard run dev
npm --workspace @pie-lab/pie-chat run dev

The dashboard uses NEXT_PUBLIC_PIE_API_BASE_URL when you need a different API server:

NEXT_PUBLIC_PIE_API_BASE_URL=http://127.0.0.1:4873 npm --workspace @pie-lab/dashboard run dev

Pie Chat uses the same variable:

NEXT_PUBLIC_PIE_API_BASE_URL=http://127.0.0.1:4873 npm --workspace @pie-lab/pie-chat run dev

From the repository:

./pie-test.sh

With a linked or globally installed CLI:

pie

Useful commands inside the TUI:

Project settings already register apps/chat as a local package, so running pie from the repository root loads the chat bridge commands automatically.

Start the server:

npm --workspace @pie-lab/server run dev

Example OpenAI-compatible request:

curl http://127.0.0.1:4873/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model": "auto:chat",
    "messages": [
      { "role": "user", "content": "Say hello from pie-lab." }
    ]
  }'

Useful operational endpoints include:

• GET /usage
• GET /usage/summary
• GET /providers
• GET /provider-connections
• GET /routing-policy
• GET /learning

The dashboard uses the same local API.

Start:

npm --workspace @pie-lab/dashboard run dev

Open:

http://127.0.0.1:4876

Main pages:

• Overview: router and system summary
• Providers: provider status, connection CRUD, OAuth/login flows
• Usage: request records, origin/endpoint grouping, cost and token totals
• Quota: quota snapshots and account availability
• Routing: aliases, intents, combo policies, route previews
• Proxy: proxy pools and provider connection bindings
• Media: embeddings, web fetch/search, audio, image endpoint tests
• Learning: memory, background review proposals, and skill curator operations
• Logs: recent operational records

Start the API server first, then the chat app:

npm --workspace @pie-lab/server run dev
npm --workspace @pie-lab/pie-chat run dev

Open:

http://127.0.0.1:4877

Pie Chat requests are recorded with clientOrigin=pie-chat:web, so the dashboard can separate browser chat usage from CLI and bridge usage.

There are two ways to connect Telegram or Discord.

• pie gateway is the recommended long-running process. It runs without an open TUI session and also ticks scheduled cron jobs.
• The bridge extension from apps/chat/extension is still available when you want a live local pie session connected to a channel.

The extension bridge is not the Next.js web server.

Because .pie/settings.json registers ../apps/chat, a normal pie session from the repository root loads the bridge commands:

pie

Configure accounts and channels:

/chat-config

Connect the current session to one configured channel:

/chat-connect

Or connect directly:

/chat-connect telegram-pio/dm-donghak-kim

For long-running workers:

/chat-spawn-all
/chat-workers
/chat-open-all

Worker mode requires tmux and a pie command on PATH because tmux workers launch pie directly. The pie executable comes from @pie-lab/coding-agent; the chat bridge itself is loaded from apps/chat through .pie/settings.json.

If you are using only ./pie-test.sh, link the local CLI first:

npm run build
npm link --workspace @pie-lab/coding-agent

For one-off bridge testing without project settings, load the chat extension explicitly:

pie -e apps/chat

Chat bridge state is stored in:

~/.pie/agent/chat/

More details are in docs/chat-usage.md.

pie gateway is the Hermes-style always-on process for external chat and scheduled automations. It uses the same config file as /chat-config:

~/.pie/agent/chat/config.json

Configure channels either from the TUI with /chat-config or from the CLI:

pie gateway setup

Run it in the foreground:

pie gateway run

Check or stop it:

pie gateway status
pie gateway stop

Configure OpenAI audio for gateway STT/TTS without exporting keys every time:

pie gateway audio set
pie gateway audio status
pie gateway audio remove

Install it as a user service:

pie gateway install
pie gateway restart
pie gateway uninstall

On macOS this creates a LaunchAgent. On Linux this creates a systemd user service. While the gateway is running, Telegram/Discord messages can start full Pie agent turns with router usage tracking, Learning Loop tools, global/project skills, chat history, file attachments, and cronjob scheduling. Cron jobs that use deliver: "origin" reply back to the chat where they were created.

Periodic nudge: Set nudgeIntervalMinutes on a channel in ~/.pie/agent/chat/config.json to have the gateway automatically trigger a proactive agent turn after that many minutes of user inactivity. The agent can use [SILENT] to suppress delivery if there is nothing useful to say.

Scheduled jobs (pie cron):

pie cron status          # shows gateway running state + job summary
pie cron create          # --schedule "0 9 * * *" --timezone "Asia/Seoul" ...
pie cron list

Key scheduler features:

• IANA timezone support for cron expressions (--timezone "Asia/Seoul")
• Grace window: missed runs are fast-forwarded instead of executed late
• Wake-gate: script can output {"wakeAgent":false} to skip LLM and deliver stdout directly
• Separate timeouts: scriptTimeoutSeconds (default 120s) and timeoutSeconds (agent, default 600s)
• [SILENT] prefix in agent response skips delivery silently

pie-lab includes a Hermes-style Learning Loop adapted to the pie runtime.

The request flow is:

user request
  -> local memory + skill index
  -> pie agent turn
  -> assistant response
  -> background learning review
  -> memory update / skill proposal or write
  -> next turn can reuse it

Important paths:

~/.pie/agent/memories/MEMORY.md
~/.pie/agent/memories/USER.md
~/.pie/agent/skills/<skill>/SKILL.md
.pie/skills/<project-skill>/SKILL.md

The dashboard Learning page can inspect memory, review records, proposal approve/reject actions, and skill curator runs.

Skill Curator Consolidation: After a configurable interval (default 7 days), the curator runs an LLM pass to identify clusters of narrow skills (e.g. gateway-auth-*), merge them into an umbrella skill, and archive the siblings. Run manually with pie curator consolidate.

npm run dev clears the fixed pie-lab ports before starting:

4873 API server
4876 dashboard
4877 Pie Chat

If you started apps separately and only want to clear those ports, run:

npm run dev:clean-ports

If another non-pie process intentionally uses one of those ports, stop it yourself or run the individual app with a different port instead of using the root npm run dev.

Run from the repository root and check that project packages are visible:

pie list

You should see:

Project packages:
  ../apps/chat

If a pie session was already open, run /reload or restart the session.

Check connection status:

/chat-status
/chat-workers

Restart workers:

/chat-spawn-all --restart

Inspect logs:

find ~/.pie/agent/chat -name channel.jsonl -print
tail -n 80 ~/.pie/agent/chat/accounts/<account>/channels/<channel>/channel.jsonl
tmux ls

Remember: messages typed directly into the local terminal only reply in the terminal. To send a reply back to Telegram or Discord, the turn must start from the remote chat.

Clear the Next cache and restart the dashboard:

rm -rf apps/dashboard/.next
npm --workspace @pie-lab/dashboard run dev

The dashboard dev script uses webpack mode for a more stable local HMR loop after folder renames.

Add at least one provider credential using /login, dashboard Providers, or environment variables. Then reload the session or restart the server.

• docs/README.md: documentation index
• docs/current-decisions.md: current architecture and decisions
• docs/learning-loop.md: memory, skills, Honcho, curator
• docs/chat-usage.md: Pie Chat and bridge guide
• docs/gateway.md: long-running Telegram/Discord gateway and scheduler delivery
• docs/gateway-audio.md: Hermes-scoped gateway STT/TTS, OpenAI audio key setup, and Discord voice
• docs/discord-gateway-setup.md: Discord bot setup through gateway connection
• docs/chat-e2e-checklist.md: Telegram/Discord verification checklist
• docs/usage-accounting.md: usage and cost records
• docs/deployment.md: npm and GitHub Pages deployment
• docs/origins.md: source origins and imported baselines

pie keeps the original pi spirit, but in this project it expands toward Passive Income Engineering: reusable agents, repeatable workflows, routing discipline, and automation that can keep working after the first manual effort.

The CLI command is pie. The local config root is ~/.pie/agent, and project config lives in .pie/.

MIT