Agent Terminal

The Agent Terminal is the node where Claude lives. Underneath it runs a CLI process (Claude Code, by default) inside a pseudo-terminal, with a local MCP server exposing the connected nodes as tools.

Anatomy

• Header with name, icon, Start / Stop button.
• Embedded terminal (xterm.js) where the conversation happens.
• Status showing whether the MCP server is connected.

Default size 520×480px. Use Ctrl ` to maximize when deep in a long conversation.

Starting a session

Click Start. Riggr:

1. Spins up a local MCP HTTP server on a random port.
2. Builds the tool list (riggr_*) from connected nodes and their permissions.
3. Writes a temporary config file (riggr-mcp-configs/mcp-<nodeId>.json).
4. Spawns the CLI agent configured in Settings — claude-code by default — with the right flags: --mcp-config <path> --append-system-prompt <text describing the nodes>.
5. A few seconds later you see Claude Code's prompt in the terminal.

Supported CLI types

In Settings → Agent → Default CLI agent you pick:

• claude-code — the recommended path. Runs claude from PATH.
• codex — OpenAI's Codex CLI. Needs to be installed.
• gemini — Gemini CLI. Same.
• custom — you define the command, args, env vars. Useful for alternative binaries or beta versions.

Login. Riggr does not ask for an AI provider key. The chosen CLI runs its own auth flow on first launch — Claude Code opens your browser to sign in with Anthropic, Codex with OpenAI, Gemini with Google. Riggr just fires the process.

You can also override per node — each Agent Terminal accepts its own cliConfig. That gets saved in the .riggr.

How the agent sees the nodes

The agent doesn't see the canvas. It sees a list of tools with descriptive names:

riggr_list_connected_nodes        → "what nodes are wired to me?"
riggr_read_code_node_1            → "read the content of the Code named X"
riggr_write_to_code_node_1        → "replace the content"
riggr_run_terminal_command        → "run this in terminal Y"
riggr_run_db_query_2              → "run this SQL"
riggr_navigate_to_url_3           → "open this URL in the webview"

The list changes as you connect/disconnect nodes. It calls riggr_list_connected_nodes periodically to stay current.

More concrete = better

Compare:

• Bad: fix this bug.
• Good: the login test is failing with a timeout. Read the test file and the login handler and tell me which hypothesis looks like the cause.

The second version says what's wrong, where to look, and what you want back. Without that, the agent guesses.

Plan before executing

For irreversible actions — running a migration, deleting files, any rm -rf — ask for a plan first:

Show me what you intend to do before running. Don't execute yet.

You review, tweak, approve. Worth the friction.

Continuing a session

Claude Code keeps history per session ID. Riggr saves the claudeSessionId in the node's .riggr — on restart, it passes --resume <uuid> and the conversation picks up where it left off.

If the session is corrupted or Claude's server expired it, Riggr detects it (the binary exits within 5s after --resume) and drops the ID, starting fresh.

Stopping gracefully

Stop sends Ctrl+C twice (Claude Code only closes on the second) and waits 400ms for a graceful exit. If it doesn't die, force-kill the tree (cmd → claude.cmd → claude.exe).

Multi-agent delegation

Wire two Agent Terminals and the first can hand work off to the second. See connectors agent-delegate, agent-send, agent-read-output, agent-interrupt in Connector list.

Use it when a sub-task deserves a focused agent — main agent on code that delegates anything database-related to an agent wired only to Database.

RIGGR.md as persistent memory

Enable Settings → Agent → RIGGR.md. The system prompt now instructs the agent to:

• Read RIGGR.md at the workspace root before starting.
• Update it with important decisions during work.
• Treat that file as long-term project memory.

Then the agent knows next session "ah, this project uses pnpm, avoid installing with npm" without you having to repeat yourself.

When it stalls

If it loops, repeats itself, or stops making sense, open a fresh conversation (send /clear to Claude Code) or spin up a new Agent Terminal. Fresh context fixes most cases.

To speed all of this up with the keyboard, see Essential shortcuts.