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

# Commands

> The full v1 command surface, access rules, and what is deferred to v1.1.

Celly registers guild-scoped slash commands (instant updates) plus a `!` shell
prefix. `/project` uses subcommands.

## Project management

| Command                                                     | Access     | Behavior                                                                                                                                                              |
| ----------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/project add name:<name> path:<path>`                      | owner      | Register an existing directory under `PROJECTS_ROOT`; runs the create saga.                                                                                           |
| `/project create name:<name> [clone:<url>] [branch:<name>]` | owner      | Create a directory under `PROJECTS_ROOT`, then add it. `clone` must be a single `https://` repository URL; `branch` requires `clone` and defaults to the remote HEAD. |
| `/project list`                                             | authorized | List projects with sandbox status and health.                                                                                                                         |
| `/project status name:<name>`                               | authorized | Status, port, health, and session count (ephemeral; password masked).                                                                                                 |
| `/project start name:<name>`                                | owner      | Wake the sandbox and supervised server (recreates it if missing).                                                                                                     |
| `/project stop name:<name>`                                 | owner      | Stop the supervised server, then the sandbox.                                                                                                                         |
| `/project restart name:<name>`                              | owner      | Restart the supervised server without stopping the sandbox.                                                                                                           |
| `/project remove name:<name> confirm:<name>`                | owner      | Typed confirmation; remove sandbox, rows, and channel.                                                                                                                |

<Note>
  Owner-only means the guild owner, or a member with `OWNER_ROLE_ID` (or
  `Administrator`/`Manage Server`). `list` and `status` are available to any
  authorized member. Access is decided by `ACCESS_ROLE_ID` / `BLOCK_ROLE_ID`,
  with block checked first.
</Note>

## Sessions

| Command                            | Access     | Behavior                                                                                                          |
| ---------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `/new [prompt]`                    | authorized | Start a new thread/session in this project channel.                                                               |
| `/resume`                          | authorized | Pick a past session (ephemeral select) and resume it in a new thread.                                             |
| `/abort`                           | authorized | Abort the current run in a thread, or every active run in the project channel.                                    |
| `/model`                           | authorized | Choose the model for this thread, or the channel default in a project channel (two-step provider → model select). |
| `/agent`                           | authorized | Choose the agent for this thread, or the channel default in a project channel (select).                           |
| `/attach`                          | thread     | Show the exact `sbx exec` + `opencode attach` command for this thread's session (ephemeral).                      |
| `/session-id`                      | thread     | Show this thread's session id and the attach command behind a spoiler (ephemeral).                                |
| `/queue`                           | authorized | Show the first 10 queued prompts for this thread with Remove and Clear buttons (ephemeral).                       |
| `/undo`                            | authorized | Revert the session to its last user message.                                                                      |
| `/redo`                            | authorized | Restore messages reverted by the last `/undo`.                                                                    |
| `/diff`                            | authorized | List up to 10 changed files as `status path (+adds/-dels)` plus totals (chunked).                                 |
| `/share`                           | authorized | Share the session and post the share URL.                                                                         |
| `/unshare`                         | authorized | Stop sharing the session.                                                                                         |
| `/compact`                         | authorized | Summarize the session using the thread's model; errors when no model is set.                                      |
| `/context-usage`                   | authorized | Show the last assistant message's token use against the model's context limit with a 20-cell bar (ephemeral).     |
| `/mode mode:<auto\|buttons\|plan>` | owner      | Set the approval mode for this project channel (stored as `approval_mode:<channelId>`).                           |

## Scheduled tasks

| Command                                                        | Access     | Behavior                                                             |
| -------------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| `/task add channel:<#channel> prompt:<text> every_minutes:<n>` | owner      | Schedule a recurring prompt in a project channel (minimum 1 minute). |
| `/task list`                                                   | authorized | List scheduled tasks with their next run.                            |
| `/task remove id:<n>`                                          | owner      | Remove a scheduled task by id.                                       |

## Approvals and questions

Approval mode is per project channel. `/mode` writes the override; the
`APPROVAL_MODE` environment value seeds the global default on first boot.

* `auto` — the bot answers every permission request from the enforced policy
  immediately, exactly like previous releases.
* `plan` — a dry run. Read-only tools (`read`, `glob`, `grep`, `list`, `find`)
  run; `bash`, `edit`, `write`, `patch`, `external_directory`, `webfetch`,
  unknown tools, and sensitive-path reads are rejected.
* `buttons` — read-only tools run; every other non-denied request posts an
  **Approve once / Always allow / Reject** message in the thread. Requests time
  out after 5 minutes and are rejected. Deny-listed commands, sensitive paths,
  and unknown tools are rejected without asking.

In `buttons` mode an agent question renders as buttons (one to five options), a
string select (six to twenty-five options), a **Custom answer** button that
opens a modal, and a **Reject** button. Multi-question requests collect answers
in order. Questions time out after 5 minutes and are rejected. `auto` and
`plan` modes reject questions rather than interrupting the run.

Clicking a button from a previous bot process answers "this request is no
longer active"; pending requests are not persisted across restarts.

## Worktrees and forks

| Command                    | Access     | Behavior                                                                                                                                                 |
| -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/worktree status`         | authorized | Show this thread's worktree path, branch, and clean/dirty state.                                                                                         |
| `/worktree new [name]`     | authorized | Create `<project>/.celly/worktrees/<slug>` on branch `celly/<slug>`; appends `.celly/` to the project's `.gitignore` on first use.                       |
| `/worktree merge`          | owner      | Refuse when the worktree or the project root is dirty, then `git merge --no-ff` the worktree branch into the project root. Conflicts are listed by file. |
| `/worktree remove [force]` | authorized | `git worktree remove` this thread's worktree; `force` discards uncommitted changes.                                                                      |
| `/fork [prompt]`           | authorized | Fork this thread's session into a new thread, copying model, agent, and worktree.                                                                        |
| `/btw <prompt>`            | authorized | `/fork` with a `btw · ` title prefix.                                                                                                                    |
| `/last-sessions [count]`   | authorized | Ephemeral list of recent threads in this channel (default 5, max 10).                                                                                    |

## Cost and providers

| Command                 | Access     | Behavior                                                                                       |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `/cost`                 | authorized | Show this thread's and channel's accumulated cost, tokens, and the session budget (ephemeral). |
| `/budget show`          | owner      | Show this channel's session budget (ephemeral).                                                |
| `/budget set usd:<usd>` | owner      | Set this channel's session budget in USD; `0` disables it (ephemeral).                         |

Register provider credentials with `sbx secret` on the host. Alternately, a
provider's own login flow (for example `opencode auth login`) can be run inside
the sandbox over the terminal opened by `/attach`.

The model and agent lists behind the `/model` and `/agent` pickers are warmed at
startup and refreshed every 60 seconds, so the pickers open from cache rather
than fetching on demand.

## Messages and shell

| Input         | Where             | Behavior                                                                     |
| ------------- | ----------------- | ---------------------------------------------------------------------------- |
| Plain message | project channel   | Creates a thread, a session, and sends the prompt.                           |
| Plain message | thread            | Continues that session (queued if a run is active).                          |
| `!<command>`  | channel or thread | Runs `bash -lc <command>` inside the project's sandbox and posts the output. |

Text-like attachments on a message are size-capped, written to a validated
`.celly/inbox`, and referenced in the prompt. Shell output is truncated and
chunked across up to three messages with a total-length footer.

<Warning>
  `!<command>` runs with the same privilege as the agent inside the microVM. It
  cannot run host commands, but it can do anything the sandbox allows. Treat it as
  running code.
</Warning>

## Deferred to v1.1

Features: voice messages, image attachments, OpenCode web UI, diff viewer,
tunnels/screenshare, forum-channel layout, cloud sandboxes.

The OpenCode web UI is intentionally not published (the sandbox server stays
loopback-only); attach from a terminal instead — see the
[terminal attach guide](/guides/terminal-attach).

See the [architecture reference](/reference/architecture) for what happens under
the hood when you run these.