---
name: console-ipc
description: Use the local console-ipc Rails console server for fast, stateful Ruby/Rails inspection in petalmd.rails. Trigger when Codex needs to debug Rails behavior, fetch local database data, inspect models/services/scopes/serializers/permissions, run repeated Rails snippets, define temporary helpers or monkey patches, validate source changes with reload!, or avoid repeated Rails boot from rails runner while working as an AI coding agent.
---

# Console IPC

Use `bundle exec console-ipc` as a fast, stateful `rails runner` alternative. Rails boots once; later `run` commands reuse
the same process, local variables, helper methods, monkey patches, database connection, and loaded app context. This is
best for AI coding agents that need to inspect data, try snippets, edit code, `reload`, and retry quickly.

## Workflow

1. Start once from the Rails app root when no console is listening. `start` daemonizes and returns only after Rails is
   loaded and the socket is ready:

```bash
bundle exec console-ipc start > log/console-ipc.log 2>&1
```

2. Run small snippets with `run`; prefer `--json` for machine-parsed output:

```bash
bundle exec console-ipc run 'account = Account.last'
bundle exec console-ipc run 'account.email'
bundle exec console-ipc run --json 'account.attributes.slice("id", "email")'
```

3. Keep state across runs to iterate:

```bash
bundle exec console-ipc run 'def explain(record); record.attributes.slice("id", "created_at"); end'
bundle exec console-ipc run --json 'explain(Account.last)'
```

4. After editing source files, reload the already-running process and rerun the same probe:

```bash
bundle exec console-ipc reload
```

5. Stop or reset only when needed:

```bash
bundle exec console-ipc stop
bundle exec console-ipc reset
```

## Agent Guidelines

- Prefer `console-ipc run` over `rails runner` for repeated local inspections; Rails boots once.
- Prefer `--json` when the result will be parsed by the agent.
- Keep snippets small and explicit. Assign intermediate objects or helper methods when follow-up commands need them.
- Use read-only snippets by default. Mutate local data only when the user asks or the task clearly requires it.
- Use `reload` after editing source files. Do not call `reload` for helper methods or monkey patches sent with `run`.
- Start once, reuse `run`, and avoid restart churn. Restart only for stale sockets, "no console is listening", or
  contaminated process state. Use `start --foreground` only to debug the console process directly.
- Use `reset` when process state is confusing or contaminated.
- Use `--socket PATH` for parallel console sessions.

## Common Commands

```bash
bundle exec console-ipc run 'Rails.env'
bundle exec console-ipc run 'Account.limit(5).pluck(:id, :email)'
bundle exec console-ipc run 'def explain(record); record.attributes.slice("id", "created_at"); end'
bundle exec console-ipc run --json 'explain(Account.last)'
```