maddada/ghostex/ghostex-agents

ghostex-agents

Ghostex lets one agent launch, message, read, and close other agent sessions through the ghostex CLI (gx is the same binary). The CLI help is the source of truth for every command, flag, and JSON shape. Read it before you act, and never rely on command shapes you remember from an earlier run.

Read the help first

ghostex agents --help   # who am I, which agents exist, create, list, send, read, close
ghostex --help          # full catalog: create-agent --model/--effort, wait-for-text,
                        # read-session-chat, select-session-chat-model, queues, sleep/wake

ghostex agents --help covers identity, recipients, the sender block other agents see (after the message body in current versions, before it in older ones), delivery modes (default, interrupt, queue), reading replies, and closing. ghostex --help lists the session-level verbs around it, including the one that starts an agent with a specific model and effort for that session only, and the one that changes model or effort on a session that already exists. If a verb in this skill is missing from the help on this machine, the installed Ghostex is older than the verb: tell the user to update instead of guessing a replacement.

A pasted Copy Details block

When the user pastes a block that starts with Ghostex Session (from the sidebar's Copy Details), it describes another session: its agent, title, Global Ref, Agent Session ID, zmx name, and the project and path it works in. Use the Global Ref for every send, read, wait, and close, and treat the path as that agent's working folder when you agree on file ownership. The block does not say whether the session is running or busy: check ghostex agents list --all --json before you send.

When the user wants one agent to run the work

When the user wants an agent that keeps handing work to other agents and reporting back ("be my lead on this", "run these as parallel threads and tell me when they are done"), a Ghostex coordinator does that with supervision built in: Ghostex sends it each thread's final message and every question a thread is stuck on, so nothing has to poll. Start one with ghostex coordinator create. ghostex coordinator … works on every release since 2026-09-30 (ghostex orchestrator … is an alias on releases from 2026-10-10 on, and older briefs use it), so if ghostex coordinator --help is missing, the installed Ghostex is older, so use the workflow below instead. If you are a coordinator yourself, follow ghostex coordinator guide rather than the waiting habits below. Name a thread after its task in 3 to 6 words. If you are a thread and your coordinator's message starts a task your title does not describe, rename yourself first with ghostex coordinator rename-self "<3 to 6 words>" (a release newer than 10.23.0, so 10.24.0 or later); if it says the user renamed you, keep that name. Rename a thread only that way: ghostex rename-command records the user's own rename, which then locks the name, and ghostex rename-session skips the user's-rename check. Run by a coordinator, ghostex agents create also links the new session as one of its threads. When the user wants a separate session they chat to directly, add --standalone (not linked, no reports to the coordinator), and use ghostex coordinator unlink <thread-ref> to turn an existing thread into one (both need 10.24.0 or later).

Check what another session is doing

Read its conversation, not its screen:

ghostex read-session-chat <ref> --last 2 --format text

That prints the chat as the chat view shows it: the user's messages, the agent's replies, and each tool call as a one-line summary (no tool output). --last <n> keeps it to the newest rows; --role user, --grep, --since and --all narrow or widen it (see "Read another thread" below). Reading never wakes a sleeping session.

Read the terminal screen only when the chat cannot answer (a stuck prompt, a dialog, an agent that writes no transcript): ghostex read-text <ref> shows the screen now. Claude Code draws a faint guess at the user's next message in an empty input box; newer versions label it "(faint suggestion from Claude, not typed: the input box is empty)". Never treat it as a typed message or submit it.

Results come to you: ask the agent to ghostex agents send its result back (see step 7 below). Do not poll or sleep to watch it; end your turn and wait.

Core workflow

1. Know where you are. Resolve your own session and project from the CLI

(whoami in the agents help), never from whichever pane has focus. Pass the project id explicitly when you create sessions so they land in the right project.

1. Pick the agent, model, and effort. List the configured agent types and

use their ids. An agent the user turned off is not listed and is refused; pick a listed one instead of passing --allow-hidden, unless the user asked for that agent. When the user names a model or an effort level, pass them through the flags the help documents. If a launch fails on a model or effort value, report the exact error; do not substitute another model.

1. Hand over a self-contained task. A new agent starts with none of your

context. State the goal, the files it owns, what it must not touch, how to prove the work is done, and what to report back. Put anything long in a file and point the agent at it; keep the message itself short.

1. Record the global reference from the create result and use it for every

later send, read, wait, and close. Titles and short ids can be ambiguous.

1. Send with the default delivery, every time. It reaches a busy agent at

its next input boundary and wakes a sleeping one. A busy or sleeping recipient is never a reason to add --queue; replies, acknowledgements, and progress notes all go out with the default. Use --interrupt only for an urgent correction, and --queue only when the user asks for it or when the point is to leave the next task waiting: read the agent's final message first, then queue. A queued message waits as long as the current turn does, so one sent to an agent that works for hours sits unread for hours and the sender sees nothing but "queued". If an older Ghostex refuses a send because the session is not running, run ghostex wake <ref> and send it again with the default once the session is running; do not switch to --queue.

1. Confirm delivery. Newer CLIs answer delivered once the recipient's

transcript shows the message; accepted, pending, and queued mean it is not there yet, and older CLIs only ever say accepted or queued. Unless the result says delivered, read the session chat (or the queue) before you assume the agent is working on it, and before you ever send the same message again. ghostex coordinator start-thread likewise answers started only once the thread's transcript shows the brief, else pending with the reason; older CLIs print "Started thread" without checking, so read the thread's chat. None of these means the agent has read it. Newer CLIs print a sendRequestId with every send (and in a failed send's error); to retry that same message, add --request-id <that id> and Ghostex delivers it at most once. Older CLIs reject the flag; read the chat instead. In PowerShell, send text containing backticks with --body-file or single quotes: inside double quotes a backtick is an escape character.

1. Wait on a signal, not a guess. Ask the agent to send its result back to

you with ghostex agents send <the Reply to ref from its sender block> when it finishes, and to end its final message with a unique last line (for example TASK 3 COMPLETE or TASK 3 BLOCKED: reason). The send reaches you without polling; wait-for-text on the sentinel is the backup. If the task writes a results file, its appearance is a third signal: act on whichever arrives first. Idle alone does not prove the work is complete.

1. Read the result, then decide. Read the agent's reply, check the work

yourself when it matters, and only then close the session or send the next task.

A session that can't start or is stuck

When an agent session could not start ("has no saved login", a usage limit) or hangs:

ghostex accounts                                              # every Claude/Codex account: state, usage, resets, sessions
ghostex agents switch-account <ref> --account <number|email>  # move it to a ready account, same conversation
ghostex agents reload <ref>                                   # stop and restart its agent, same conversation

Pick a ready account with room for switch-account; it refuses one that needs signing in and names those that work. It refuses a session in the middle of a turn; --force ends that turn, switches, and sends "." so the agent carries on. reload loses whatever the current turn was doing, so interrupt a merely busy agent instead. Tell the user which session you moved or reloaded. These verbs need a Ghostex release newer than 10.23.0 (10.24.0 or later); when ghostex accounts is an unknown command, tell the user the session is stuck and needs Switch Account or a reload from the app.

Read another thread (past or present)

Use this when the user asks what was said or decided in another session ("check my messages in that thread", "did we already talk about this"). Read it through the CLI, not the agent's raw transcript file: the CLI works for every agent type, keeps the thread in order, and marks harness-injected rows.

1. Pick the reference. Pass whatever the user pasted: a sidebar Copy Details

block gives a Global Ref (S…:P…:G…), which is best, plus an Agent Session ID and a zmx name; older releases also list a Session ID and Routing ID. All of them work. A title works when it is unique. If two sessions match, the error lists their global refs; pick one. Sleeping sessions read fine, and reading never wakes them.

1. Search first, then read. Look for the topic, with one row of context so

each hit comes with its reply:

``bash ghostex read-session-chat <ref> --grep "mobile|react native" --context 1 --format text ``

--grep is case-insensitive, | separates alternatives, and it searches the whole thread. Matched rows say match in their header; the rows around them are context. Add --role user to match only what the user typed.

1. Read the whole thread when the search is not enough.

--all --format text prints every turn as prompt plus final reply, with the tool work collapsed into one note. --all --role user --format text lists just the user's messages, the quickest way to recover what they asked for and decided. Output is large for long threads: trim it with --last <n> (the newest n rows) or --since <local date or time> instead of printing everything. Text output is in local time with the UTC offset in its header, so convert before comparing it with UTC timestamps from other output. Add --history-mode detail only when you need every tool call. ghostex read-session-chat --help lists every flag.

1. Check the thread's own records. Long threads usually keep a plan or

progress file (docs/<date>/<topic>/PLAN.md, PROGRESS.md) that the thread's last messages link to. Read it for the current state instead of reconstructing it from the chat.

1. Report what you found with its date, and say which parts are decisions

the user made and which are only the other agent's proposals.