# Devtools

Free workshop: [how to burn a trillion tokens and get good results](/tokenmaxx#interested).

## What it does

`packages/devtools` adds `rat_*` capabilities to a development composition. They list, read, dispatch, replay, and diff capability calls. `CallWatch` surrounds the approval-gated handler, including denied calls. `watchActor` lets lifecycle machines report states and events through `ActorWatch`. Both watchers default to no-ops without the recording layer.

The local web development backend records calls and serves the overlay, RPC, and MCP tools under `/__rat`. The CLI enables its devtools surfaces with `--devtools`, bound to loopback only. These are development tools, not public hosted capabilities.

## The standard

- Tools dispatch through the capability's schemas and handler; they are not a second domain API.
- Recorder code and test people stay in development compositions 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 composition after running a lifecycle capability. A missing recording layer means no recording, not proof that nothing 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.


## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](<https://ratstack.sh/llms.txt>)
- Change log → What changed in the files served here, newest first. → [Read page](<https://ratstack.sh/log>)
- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](<https://ratstack.sh/llms-full.txt>)
- log.md → The generated change log as Markdown. → [Read page](<https://ratstack.sh/log.md>)
- 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>)