Devtools

What it does

packages/devtools adds rat_* capabilities to a development application. A capability is one named action with shared value definitions and a server-side handler, the code that implements it. The tools list and read calls, call an action, run a recorded call again, and compare results. CallWatch surrounds the handler’s approval check and records denied calls too.¶

A state machine defines named states and the events that permit movement between them. An actor is a running unit that processes events or performs work for a machine. watchActor lets lifecycle machines report states and events through ActorWatch. Both watchers do nothing unless the application supplies recording.¶

Effect describes work with typed failures³⁶ and required services. A service is a named interface for one job.¶

A Layer describes how to build services and supply their construction dependencies. The recording Layer supplies the watchers.¶

The local web development backend records calls and serves the overlay, RPC, and MCP tools under /__rat. RPC lets a client call a named server operation. MCP²⁷ means Model Context Protocol, which lets an agent discover and call tools.¶

The command-line interface (CLI) enables its devtools interfaces with --devtools. They are available only from the same computer. These capabilities are available only in development.¶

The standard

Tools call existing capabilities through their schemas and handlers. A schema defines the accepted values.¶
Recorder code and test people stay in development applications and tests.¶
Every Effect-backed lifecycle actor is handed to watchActor.¶
Production bundles contain no web development modules, devtools code, or test people.¶

How to check

Run pnpm --filter @rat-stack/devtools test for recording and tool behavior.¶
Run pnpm --filter @rat-stack/web test for the local backend and production-bundle exclusion test.¶
Run pnpm lint for no-devtools-in-production and watch-effect-actors.¶
Inspect rat_list_actors, rat_list_transitions, and rat_get_actor in a development application after running a lifecycle capability. Without a recording Layer, these tools cannot show whether a lifecycle ran.¶

Sources

Devtools package. GitHub joelhooks/rat-stack. Call recording, replay, diff, and inspection capabilities. Accessed 2026-10-01.
Call watcher. GitHub joelhooks/rat-stack. Ambient call observation without production recording. Accessed 2026-10-01.
Actor watcher. GitHub joelhooks/rat-stack. Ambient lifecycle observation. Accessed 2026-10-01.
Production bundle test. GitHub joelhooks/rat-stack. Exclusion of development code and test people. Accessed 2026-10-01.

Last changed 2026-10-07 in f77853d. Source on GitHub. Change log.

Linked from

Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Devtools — Development-only capabilities inspect calls and lifecycle transitions without entering production bundles.
Change log. What changed in the files served here, newest first.
Devtools — edited: feat(learn): teach cards 83 to 111 and finish the deck’s plain lines
Effect + Alchemy peer patterns. Source-grounded patterns from repos on nearby Effect and Alchemy pins.
Keep watchActor and ActorWatch in devtools as our single inspection path.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Rat Stack systems | rat-stack. The systems rat-stack ships, the standard each keeps, and how to check it.
Devtools — Development-only capabilities inspect calls and lifecycle transitions without entering production bundles.
Source change history (log.md). The generated change log as Markdown.
Devtools — edited: feat(learn): teach cards 83 to 111 and finish the deck’s plain lines
Trace operations where they mean something. Name useful operations, add safe context, and distinguish creating a span from delivering it to a backend.
Devtools records capability calls and watched actor lifecycles.