AGENTS.md

ThinkRail

The agentic IDE that gets better every time you use it, built around the pi coding agent. The app is a thin host that runs pi and bridges it to a rich UI; pi owns models, skills, compaction, cost, and session state.

Read context proportionally

• Use goal-and-requirements.md for the product's goal, principles, capabilities, and non-goals.
• Use architecture.md for system topology, cross-module decisions, and repo-wide invariants.
• For a pi upgrade or a host workaround around pi, read pi-compatibility.md: verify every applicable removal gate against the installed SDK, update the registry, and report what was removed or retained.
• Read the owning SPEC.md when work is governed by or may alter a module boundary, contract, invariant, documented behavior, or architecture decision.
• Localized work does not require unrelated specs or a full repository map.

Module structure and boundaries

Clear, fractal module boundaries are a top-priority requirement:

• Every package and meaningful directory-level sub-module has a SPEC.md stating its responsibility, public surface, allowed dependencies, and forbidden reaches.
• A sub-module exposes an index.ts barrel as its only public surface; siblings import through the barrel, never internals. Per-file imports remain only where a barrel would defeat code-splitting or a library convention, such as apps/web/src/panels and packages/ui.
• Dependency edges between sibling sub-modules live in the parent module's SPEC.md, not each leaf.
• A change that moves or blurs a boundary updates the owning spec first. Cover public surfaces and boundary rules with tests where practical, but do not manufacture coverage for a localized change.

Engine and architecture

• Run pi in-process through @earendil-works/pi-coding-agent (createAgentSession), never as a subprocess and never through a second agent runtime. Fatal provider/agent faults can take down the host; that lack of crash isolation is accepted.
• The three rings are engine host (packages/server + packages/shared), typed wire (packages/contracts), and independently shippable UI (apps/web). apps/cli and apps/desktop are thin launchers over the same host.
• Use only the @earendil-works/* package scope. @mariozechner/* is deprecated.

Repo-wide invariants

• apps/web depends on contracts, locales, ui, extension-api/web, resource-renderers, and thinkrail-extensions/*/web only, never server or shared.
• User-facing UI text is a key in packages/locales/en.json rendered through @thinkrail/locales/react; the lint gate rejects hardcoded JSX text and text attributes.
• Never value-import pi into browser-bundled code. Import types only from the pi-ai / pi-agent-core package roots; @earendil-works/pi-coding-agent is server-only.
• One id model: UI tab id versus session.sessionId; there is no separate pi UUID.
• pi owns state. The host exposes what pi reports rather than recomputing cost, stats, or state.
• Streaming semantics: text_delta / thinking_delta append; tool_execution_update.partialResult replaces.
• prompt() throws while a session is streaming; use steer() / followUp(). Forward errors through the event stream and thrown method result rather than treating them as a crash signal.
• Automatic work ends at agent_settled, never agent_end; retries, compaction, recovery, or queued continuations may follow an attempt-level agent_end.
• UI panels are layout-agnostic; the shell arranges them.
• Errors are reported to PostHog Error Tracking unconditionally, but only as a classifier — type, code, source/scope/request method and ThinkRail-only stack frames — never message text. Give a failure worth telling apart a CodedError code rather than relying on its message. Host diagnostics that carry an error go through logger(scope), not console.*. The allow-list lives in packages/server/src/analytics/SPEC.md.
• The transport host endpoint is a parameter, defaulting to same-origin; server.welcome carries the protocol version.

Web UI context

For web UI work, read apps/web/SPEC.md and the owning sub-module spec. Styling uses Tailwind v4 utilities mapped to generated semantic CSS-var tokens: never inline style objects, raw hex, internal palette names, or unknown token utilities. Read apps/web/src/styles/COLOR.md for color work and apps/web/src/styles/SPACING.md for spacing work. Use @remixicon/react icons (Line by default, Fill when active) and owned shadcn/Radix primitives from @thinkrail/ui/<primitive>; cn() lives in @thinkrail/ui/utils. These rules also apply to packages/ui, packages/resource-renderers, and extension web halves.

For conversation rendering or tool presentation, read apps/web/src/chat/SPEC.md. Presentational renderers remain props-driven; only ChatView integrates store and transport. A server capability and its UI renderer are joined by tool name through registerToolRenderer; unregistered tools use the default renderer.

Specs and comments

Specs are the durable home for intent, decisions, invariants, trade-offs, and post-mortems. Keep them concise and avoid restating code or another spec. Comments are near-zero: lint/type directives and a rare one-line hazard note are acceptable; rationale and narrative belong in the owning spec.

Verification

Local tests use disposable fixtures and have no production access. Run affected tests, fix failures caused by the requested change, and rerun them without asking for approval at each step.

• Iterate with the smallest relevant unit or focused E2E target.
• For shipped app behavior or integration changes, run the complete no-agent browser suite (bun run e2e) once after the combined implementation and before final handoff or PR — not once per TODO item or commit.
• When the change touches real agent behavior, also run the focused live specs that cover it, e.g. bun run e2e:full e2e/agent-naming.live.spec.ts; that needs no approval. Ask the user before running the complete bun run e2e:full suite: it spends real provider tokens and much more time.
• Documentation/spec-only changes and test-harness-only changes use targeted checks unless they can affect the shipped runtime.
• Fast gates: bun run check:deps, bun run check:boundaries, bun run check:seams, bun run lint, and bun run typecheck. Unit tests are bun run test; bun run check:spec-surface validates enrolled spec/barrel public surfaces; bun run check:compiler fails when a web function newly bails out of the React Compiler (or starts compiling) against the committed census baseline.
• bun run test:workflows is on-demand: it uses real provider tokens and is not a commit/CI gate.
• Binary and desktop artifact modes have separate gates; use them when changing those artifacts.

All runner modes, isolation guarantees, credential handling, cancellation behavior, and debugging commands live in e2e/SPEC.md; workflow harness details live in e2e/workflows/SPEC.md.

Handoff hygiene

Green gates are necessary but not sufficient:

• Before a local handoff, review the task-scoped working tree and commits. Before opening or updating a PR, review the full branch diff against its base plus the working tree.
• For nontrivial implementation, do a subtraction pass: remove avoidable abstractions, state owners, dependencies, compatibility layers, and fallbacks. Report material removals and justify layers that remain; do not add ceremony for a localized edit.
• Never add biome-ignore, @ts-expect-error, @ts-ignore, eslint-disable, or as any merely to make a gate pass. Treat the error as a design signal. If a suppression is genuinely required, get explicit user approval first.
• Audit newly added comments and suppressions in the same diff range being reviewed. Do not let prior, unrelated branch history contaminate a task-local handoff.
• Centralize duplicated nontrivial derivations. In the web app, derived store state belongs in selectors and writes that always travel together belong in one atomic action.
• When replacing a pattern or state model, search for every old occurrence and migrate it, or name the intentional survivors.
• README.md is the user-facing front page. For a change that adds, removes, or renames a user-visible capability, or alters installation or analytics behavior, review its claims and update the affected ones in the same change; refresh a screenshot under .github/readme-assets/ when the UI it depicts changes materially.
• Apply safe cleanup that is inside the approved scope. Ask only for destructive, out-of-scope, or product-level decisions.
• Use the shipping-a-pr skill for PR lifecycle work, including screenshot expectations and PR templates. When creating an issue programmatically, reproduce the selected issue template and pass its frontmatter labels.

Stack

Bun + Turbo monorepo · TypeScript strict · React 19 + Zustand + Tailwind v4 · in-process pi (Node >= 22.19). App state lives under ~/.thinkrail.

Dependencies pin exact versions. Cross-cutting dependencies are pinned once in the root workspaces.catalog and referenced through catalog:; peer dependencies and local protocols are the only exemptions. architecture.md Decision #10 owns the rationale.