Home/Tutorials/Living agent cards

Tutorial 01 · Living terminal bot cards

Your terminal, with a pulse.

Turn the Claude Code, Codex, or Grok Build session already running in a terminal into a living agent card. The process keeps running in the same PTY, so you can switch views at any time without losing the session.

About 4 minutesNo API setupSame live PTY

Quick start

1

Start an agent normally

Open a PorkiCoder terminal in your project and launch claude, codex, or grok. Sign in through the provider CLI if it asks.

2

Show the AI panels

Press ⌘P or use the AI panels view control. PorkiCoder replaces supported raw terminal panes with living cards while their PTYs continue underneath.

3

Read the live agent state

Use the card composer to send the next prompt. The card reports WORKING, YOUR TURN, IDLE, SHELL, or STALLED with elapsed time, context, output, turns, six recent work entries, and queued follow-ups.

The important bit: card mode is a view over the existing terminal. It does not create a second chat, copy the conversation, or restart the CLI.

The card layout in 2.17.83

The message is a framed bubble above the bot, with the state chip on its top edge. On panes at least 560 pixels wide and 340 tall, the work log sits in a rail at the right: the current message and the five before it, always open. Below the bot, the segmented context bar and the statistics strip give a quick session check. Short or very wide panes stand the bot beside the bubble instead, so the message keeps its lines. COPY and the page buttons sit below the message at every card size.

The toolbar's living-card selection clears when every pane is raw or remote. Restoring a card keeps the same running terminal session. Codex 0.159 assistant updates appear without its model/path footer and shortcut hints being mistaken for answers.

Work directly from the card

The card composer writes to the same PTY input as the raw terminal. That means the provider receives exactly the same prompt it would receive if you typed into xterm.

  • Send a prompt: type in the composer and submit it while the agent is waiting.
  • Interrupt: stop a run from the card when the current direction is not useful.
  • Write more: expand the composer for a longer specification or handoff.
  • Paste an image: use Ctrl+V for Codex. Use ⌘V for the other supported CLIs; card mode inserts a temporary local path when needed.

If the agent opens an interactive screen that is easier to operate directly, switch that pane back to raw terminal view. The underlying process is already there.

Mix cards and raw terminals

Card view is pane-specific. In a multi-panel layout you can keep two agents as cards and expose the third as a raw CLI. Use the terminal control on an individual card to reveal that pane, then restore its card when you are done.

Pressing ⌘P cycles the overall view: show AI panels, restore any panes you temporarily made raw, then return to the single raw terminal view.

A good setup: keep long-running Claude and Codex tasks visible as cards, and leave the pane you are actively steering in raw terminal mode. You get a compact status wall without giving up direct terminal control.

Read a background agent's log

Hover an agent in the speech bubble or work log to open its live log. Click or press Enter to pin it, and press Esc to close. In version 2.18.5, the reading panel stays near the top of the card with a fixed size while agents stream output, rows refresh or you switch agents. Scroll back and your reading position stays put.

Taller cards reserve space above the agent list and use a smaller decorative avatar. Short panes keep the reading panel clear of the composer, and resizing the pane fits it to the available room.

Since version 2.18.6 the card also holds still while the session works beside its agents. On a card with a work log, the session's words stay in the bubble and its agents stay pinned in the log. On a short or narrow card, the bubble keeps listing the agents with the session's current line on top, so you can drop in at any time.

Since version 2.18.7 the bubble lists the agents once the session has been quiet for 30 seconds after its last message, and Claude Code agents show their latest step, so you can see what each one is doing before you drop in.

What the local 77M model does

PorkiCoder extracts the card state from the terminal output on your Mac. Its shipped 77-million-parameter namer gives each submitted turn a short label without making a naming API call.

The measured 29.3 ms figure is warm title-model inference on our M4 Max CPU benchmark. It describes the naming pass, not total interface latency and not every Mac configuration.

Manual tab names remain authoritative. The local model labels the work; it does not replace the provider agent or decide what the agent should do.

If a card is not updating

  1. Confirm the terminal is running Claude Code, Codex, or Grok Build in the foreground.
  2. Switch the pane to raw terminal view and check whether the CLI is waiting on an interactive menu, login, or pager.
  3. Return to card view with ⌘P after the provider is back at its normal conversation surface.
  4. For newly installed PorkiCoder features, start a fresh terminal session so it receives the current integration configuration.