jstm agent plan opens an interactive chat where you describe what you want an agent to do, and Joyvis — the planning assistant — drafts the agent spec with you, turn by turn. It runs full screen in your terminal as a scrollable transcript, so your messages and Joyvis’s replies render as separate readable blocks instead of a wall of text.
What it’s for
- Create a new agent from a plain-language description.
- Edit an existing agent’s draft by resuming the conversation where you left off.
You go back and forth with Joyvis until the spec looks right, then you exit. The conversation is the planning step. Turning a plan into a real agent is a separate, deliberate action.
Drafts and committing
This is the most important thing to understand about the chat.
Exiting the chat never saves or promotes anything. Your spec stays a draft.
done, quit, exit, or save, or pressing Ctrl+C or Ctrl+D — closes the chat and leaves your work as a draft. Typing save also only exits; it does not commit.
When you exit, you see a summary like this:
To turn the draft into an agent, run the explicit commit command after you exit:
plan done is the only command that commits. This separation means a mistaken exit, a closed terminal, or a dropped connection can never accidentally create or change an agent.
Picking up where you left off
Your conversation is saved on the server as you go. When you resume with jstm agent plan <session-id>, the previous turns replay into the chat and the assistant keeps full context — it remembers what you discussed. New turns continue the same planning session, so when you later run plan done, you commit the spec that includes everything you talked about.
If a resume can’t load the prior conversation — the id isn’t found, or you don’t have access — you see a short notice and a fresh draft starts. Your existing work isn’t lost.
Lost the session id? jstm agent plan list shows your sessions and their status.
What it looks like
Your blocks show exactly what you typed. Joyvis blocks render as formatted markdown. A waiting indicator appears while Joyvis is thinking, and your input is paused until the reply arrives. If a turn fails — a network blip, for example — an error message appears in the transcript and the chat stays open. Try again; your session is intact.
Referencing skills
Typing / at the start of the input, or after a space, opens a picker over the skills catalog. It filters as you type. Selecting a skill inserts the text Use the <name> skill into your message, which tells Joyvis to build the agent around that skill.
The picker covers skills only. To reference an MCP server directly, name it in your message.
Typing /help shows the key bindings without sending a turn.
Requirements
jstm agent plan needs a real, interactive terminal. It won’t run in a non-interactive environment such as a pipe, a CI job, or captured output. It fails fast with a clear message rather than falling back to a degraded mode.
See also
