@hachej/boring-agent

A pane-embeddable coding agent: an LLM agent loop, a tool catalog, and a chat UI behind one interface, with three swappable execution modes. The same agent, tools, and UI run in direct (host process), local (bwrap sandbox), or vercel-sandbox (Firecracker microVM) mode.

Install

pnpm add @hachej/boring-agent
# or: npm install @hachej/boring-agent

Peer deps (optional): react, react-dom, tailwindcss.

Usage

Server — standalone Fastify app:

import { createAgentApp } from "@hachej/boring-agent/server"

const app = await createAgentApp({
  mode: "local",                 // "direct" | "local" | "vercel-sandbox"
  workspaceRoot: process.cwd(),
})
await app.listen({ port: 3001 })

To embed routes into an existing Fastify instance, use registerAgentRoutes instead. The full IDE shell (file tree, panes, UI-bridge tools) lives in @hachej/boring-workspace, which mounts this agent.

Frontend — the chat panel:

import { ChatPanel } from "@hachej/boring-agent"
import "@hachej/boring-agent/front/styles.css"

function App() {
  return <ChatPanel apiBaseUrl="http://localhost:3001" />
}

Configuration

Set an API key for the model provider (e.g. ANTHROPIC_API_KEY). Common env vars: BORING_AGENT_MODE (default direct), BORING_AGENT_WORKSPACE_ROOT (default cwd), BORING_AGENT_SESSION_ROOT (durable Pi session storage), BORING_AGENT_PORT, and the BORING_AGENT_DEFAULT_MODEL* / BORING_AGENT_CUSTOM_MODEL* / BORING_AGENT_INFOMANIAK* provider settings. See docs/runtime.md and docs/API.md.

Documentation

See docs/README.md for the full doc index — architecture, the export surfaces (/front, /server, /shared, /eval), runtime modes and provisioning, theming, plugins, error codes, and risk/cost notes.

Contributions

I do not accept outside contributions for my projects: I don't have the bandwidth to review them, and it's my name on the result. Issues and bug reports are welcome; PRs may be used to illustrate a fix, but I won't merge them directly — I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them.

License

MIT