# Devtools

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

## 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

1. [Devtools package](https://github.com/joelhooks/rat-stack/tree/main/packages/devtools)
   GitHub joelhooks/rat-stack. Call recording, replay, diff, and inspection capabilities. Accessed 2026-10-01.

2. [Call watcher](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/call-watch.ts)
   GitHub joelhooks/rat-stack. Ambient call observation without production recording. Accessed 2026-10-01.

3. [Actor watcher](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/actor-watch.ts)
   GitHub joelhooks/rat-stack. Ambient lifecycle observation. Accessed 2026-10-01.

4. [Production bundle test](https://github.com/joelhooks/rat-stack/blob/main/apps/web/test/production-bundle.test.ts)
   GitHub joelhooks/rat-stack. Exclusion of development code and test people. Accessed 2026-10-01.

## Lore on this page

- [Handle expected failures without hiding defects](/lore/error-model)
- [MCP is another surface](/lore/mcp-is-another-surface)

## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Build and run rat-stack (README.md) → What is in the repo, how the example works, and how to run it. → [Read page](https://ratstack.sh/README.md)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Effect + Alchemy peer patterns → Source-grounded patterns from repos on nearby Effect and Alchemy pins. → [Read page](https://ratstack.sh/resources/same-version-repos)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Rat Stack systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- Trace operations where they mean something → Name useful operations, add safe context, and distinguish creating a span from delivering it to a backend. → [Read page](https://ratstack.sh/lore/trace-meaningful-operations)
