> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# jstm agent plan

> Draft and edit agent specs in an interactive chat. Drafts stay drafts until plan done commits them.

Draft or edit an agent spec in conversation with Joyvis. Exiting the chat leaves your spec a draft. Committing is the separate `jstm agent plan done` command.

```bash theme={null}
jstm agent plan --new          # create a new draft session
jstm agent plan <session-id>   # resume or edit an existing session
jstm agent plan done <id>      # commit a draft into an agent
```

## Forms

| Command                     | Action                                                                            |
| --------------------------- | --------------------------------------------------------------------------------- |
| `jstm agent plan --new`     | Open the chat on a fresh session                                                  |
| `jstm agent plan <id>`      | Open the chat, replaying the prior conversation                                   |
| `jstm agent plan`           | Error. Prints a hint naming both forms and exits `2`. Creating is always explicit |
| `jstm agent plan done <id>` | Commit the draft. The only command that saves and promotes                        |

You must choose exactly one form — `--new` or an id.

<ParamField path="--new">
  Start a new session instead of resuming one.
</ParamField>

<ParamField path="--json">
  Create the draft non-interactively and print its reserved identity as JSON, without opening the chat. Prints `{agent_id, handle, session_id}`.
</ParamField>

## Requirements

The chat requires an interactive terminal. In a pipe, a CI job, or with captured output, it exits with `jstm agent plan requires an interactive terminal.` There is no line-mode fallback.

Use `--json` when you need to create a draft from a script.

## Keys

| Key                                                         | Action                                                                     |
| ----------------------------------------------------------- | -------------------------------------------------------------------------- |
| <kbd>Enter</kbd>                                            | Send the current message                                                   |
| <kbd>Ctrl</kbd>+<kbd>J</kbd>                                | Insert a newline. Always works                                             |
| <kbd>Shift</kbd>+<kbd>Enter</kbd>                           | Insert a newline, in terminals supporting the enhanced keyboard protocol   |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                 | Recall the previous or next message you sent. Only when the input is empty |
| <kbd>PgUp</kbd> / <kbd>PgDn</kbd>                           | Scroll the transcript                                                      |
| <kbd>Ctrl</kbd>+<kbd>C</kbd> / <kbd>Ctrl</kbd>+<kbd>D</kbd> | Exit, keeping the draft                                                    |

Typing `done`, `quit`, `exit`, or `save` as a whole message also exits, case-insensitively. An empty message does nothing.

Typing `/` at the start of the input, or after a space, opens a picker over the skills catalog. Selecting an entry inserts `Use the <name> skill`. Typing `/help` shows the key bindings without sending a turn.

## Exiting and committing

Every exit path leaves the spec a draft. On exit:

```text theme={null}
  Session: 5f3a…-9b21 — spec is DRAFT (not committed).
  Resume editing:  jstm agent plan 5f3a…-9b21
  Commit the spec: jstm agent plan done 5f3a…-9b21
```

If no session was created before you exit, you see `No session was created — nothing to commit.`

## `jstm agent plan done`

Commit the draft: save, promote, then render the resulting tree.

```bash theme={null}
jstm agent plan done 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
# ✓ spec committed
```

<ParamField path="--json">
  Emit the result as JSON.
</ParamField>

## `jstm agent plan list`

List your builder sessions, newest first. Use this when a closed terminal took the session id with it.

```bash theme={null}
jstm agent plan list
jstm agent plan list --status active
```

| Option           | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--status`       | Filter by `active`, `completed`, `abandoned`, or `stale` |
| `--workspace-id` | Scope to one workspace. Defaults to all your workspaces  |
| `--json`         | Emit as JSON                                             |

## `jstm agent plan discard`

Delete a draft session and its messages. The inverse of `plan done`.

```bash theme={null}
jstm agent plan discard 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
```

| Option          | Description                  |
| --------------- | ---------------------------- |
| `--force`, `-f` | Skip the confirmation prompt |
| `--json`        | Emit as JSON                 |

## `jstm agent plan discard-all`

Bulk-delete every draft session belonging to you.

```bash theme={null}
jstm agent plan discard-all
jstm agent plan discard-all --workspace-id acme-corp/finance --force
```

<Warning>
  This deletes all your draft chats and their messages. Pinned sessions are spared unless you pass `--include-pinned`.
</Warning>

| Option             | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `--include-pinned` | Also delete pinned sessions                                       |
| `--workspace-id`   | Scope the clear to one workspace. Defaults to all your workspaces |
| `--force`, `-f`    | Skip the confirmation prompt                                      |
| `--json`           | Prints `{"deleted": N}`                                           |

## Exit codes

| Code | When                                                                                        |
| ---- | ------------------------------------------------------------------------------------------- |
| `0`  | Normal exit, including <kbd>Ctrl</kbd>+<kbd>C</kbd> or a typed exit word. The draft is kept |
| `1`  | Not an interactive terminal, or the active workspace couldn't be resolved                   |
| `2`  | A bare `jstm agent plan` with neither `--new` nor an id                                     |

## See also

* [Planning an agent in chat](/features/agent-plan-chat) — how the chat behaves.
* [Draft an agent](/guides/draft-an-agent) — walkthrough.