Index · Glossary · Cheat sheet

Install the observer CLI, attach Insider to a running development node, give your agent the welcome document, and read one quiet window per task. Then decide whether your app should depend on Insider, and set up the Insider repository itself.

Contents

Observe a running node in five minutes

You need the observer CLI and a development node on this machine. The node does not depend on Insider: the observer loads Insider into it at run time.

1. Install the CLI

The CLI is the Lab escript, insider-lab. Install it from Hex:

mix escript.install hex insider_lab

Mix installs it in its escripts directory, usually ~/.mix/escripts, and prints that directory. Add it to your PATH. Install again to update.

In an Insider checkout, use the Mix task from tools/insider_lab instead: mix insider.live takes the same operations and flags as insider-lab live. Or build the escript there with mix escript.build and run ./insider-lab live.

Make the cookie file with umask 077, so that only you can read it. The observer refuses a cookie file with group or other permission bits.

(umask 077 && openssl rand -hex 24 > ~/.my_app.cookie)
elixir --sname my_app \
  -e 'Node.set_cookie(String.to_atom(String.trim(File.read!(Path.expand("~/.my_app.cookie")))))' \
  -S mix run --no-halt

With Phoenix, run -S mix phx.server instead. The node is named my_app@<short host name>.

3. Six commands, plus a mark

Run these from any directory. Set N as an array, as shown. It then splits into words in bash and in zsh. Replace ID with the session_id that start returns.

N=(--node "my_app@$(hostname -s)" --cookie-file "$HOME/.my_app.cookie")
insider-lab live capabilities "${N[@]}" --load   # first contact: loads Insider if the node lacks it
insider-lab live welcome "${N[@]}"              # the agent's quick start
insider-lab live start "${N[@]}" --component logger --component telemetry
insider-lab live digest "${N[@]}" --session ID --human
insider-lab live events "${N[@]}" --session ID --cursor 0 --format compact
insider-lab live stop "${N[@]}" --session ID    # check the cleanup receipt

# Mark a window, act, then read only what came after the mark
insider-lab live mark "${N[@]}" --session ID --label 'about to click Confirm'
insider-lab live digest "${N[@]}" --session ID --since-mark --human

--since-mark without a label reads from the newest mark. digest, trends, events and timeline all accept it.

A read without --session uses the node's active session. stop, amend and otlp-receive still need --session. See Default session.

4. Or use Tidewave project_eval

In a Phoenix development server with Tidewave, evaluate the same operations through Insider.Live.JSON:

Insider.Live.JSON.welcome()
Insider.Live.JSON.start(%{"components" => ["logger", "telemetry"]})

The Tidewave section shows how to load Insider's compiled ebin first. If your app depends on Insider, it is already there. See Add Insider to your app.

Attach to a node you did not start

The observer can attach to any local development node that already has a name. You need three things:

  • The node's exact name, for example my_app@myhost. A different host part is refused as an unknown node.
  • A cookie file that holds the node's cookie, with mode 0600 or stricter.
  • A development, test or ci environment on the node. The node decides this.

If the node does not run Insider, capabilities reports insider_missing. Run it again with --load. If the node runs another Insider build, --load reports load_build_differs. --force-load replaces that build and ends its session, so save the session's evidence first. See Load Insider into the target and Exit statuses and error codes.

Tips

  • Point your agent at the welcome document and let it drive. The welcome is generated from the code, so it matches the Insider that is loaded.
  • Use Insider next to Tidewave, not instead of it.
  • Found something wrong? Run insider-lab live report --category bug --message '…'. Reports stay local until you send them.
  • Live observation works only on development, test and ci nodes. See Disclosure and safety.

The full flag reference is under Observer flag reference, and insider-lab live --help prints it. The cheat sheet has the commands you use most. It writes them as mix insider.live, the same commands from a checkout.

Add Insider to your app

Observation needs no dependency: --load pushes the observer's own Insider into the node. Add Insider to your app only if you want one of these:

  • The agent guides and the usage rules under deps/insider/, for the agents of your app and for mix usage_rules.sync.
  • Insider in the node for Tidewave project_eval, with no ebin to load first.

Add it for development only:

# in the deps of your app's mix.exs
{:insider, "~> 0.1", only: :dev}

The node then starts its own Insider. The observer works with it. It reports same_build: false when the two copies were compiled apart, and --load does not replace the node's copy. See Load Insider into the target.

Work on the Insider repository

Use a supported Elixir/OTP pair (1.17/27, 1.19/28, or 1.20/29; maintainer tools need Elixir 1.18 or newer). From the repository root:

mix setup      # deps.get, then activate .githooks/
mix quality    # format, warnings-as-errors, full unit suite, Credo + ex_slop
(cd tools/insider_lab && mix deps.get && mix test)

To look for test-isolation candidates in another Elixir project, compile Lab once and point the inventory at that project's test tree:

(cd tools/insider_lab && mix compile)
(cd tools/insider_lab && mix insider.candidates --root /path/to/project --path test)

A candidate is a hint, not a confirmed defect. The fixed runtime oracles that can confirm one are described under Agent-requested ExUnit candidates.

Brief the agents of your host app

A host application whose agents use Insider Live can add this to its own AGENTS.md (adjust the node name and cookie path):

## Insider Live (runtime observation)

This app can be observed while it runs with Insider Live, in development only.

- Before observing, read the welcome quick start and follow it:
  `insider-lab live welcome --node my_app@$(hostname -s) --cookie-file ~/.my_app.cookie`
  (`--full` for the whole reference, `insider-lab live --help` for the
  flags), or `Insider.Live.JSON.welcome()` through Tidewave `project_eval`.
  Install the CLI with `mix escript.install hex insider_lab`.
- Loop: start one session, act, then read `events_since` from your cursor.
  Stop the session when you are done.
- You must report Insider bugs and anything that behaves differently from the
  welcome document: `insider-lab live report --category doc_mismatch --message '…'`
  (or `Insider.Live.JSON.report/1`). Never include payloads or secrets.
  Reports stay local. The developer sends them with `insider-lab live reports submit`.
- Rules and guides: `deps/insider/usage-rules.md` and
  `deps/insider/guides/agents/live-observation.md` when Insider is a
  dependency, otherwise <https://hexdocs.pm/insider>.

With usage_rules, mix usage_rules.sync picks up deps/insider/usage-rules.md.