Seshat AIDocumentation

Documentation / Guides

Using the CLI

Every `seshat` command, the options you will use most, background runs, sessions and the terminal shortcuts.

seshat with no arguments opens the interactive terminal interface, the same as seshat chat. Everything else is a subcommand.

Commands at a glance

CommandWhat it does
seshat chatInteractive session in the terminal interface
seshat run "prompt"One task, then exit. Add --bg to run it in the background
seshat configSet the provider, model and keys, or show them with --print
seshat sessionsList, inspect, delete and prune saved sessions
seshat memoryRead and write the notes the agent keeps
seshat trustTrust the configuration files of a project
seshat loginSign in with a ChatGPT subscription (no API key)
seshat doctorCheck configuration, storage, credentials and helper tools
seshat repomapPrint a compact structural map of the repository
seshat workflow run <file>Run a workflow described in YAML or JSON
seshat companionConfigure the companion profile added to sessions
seshat ps, logs, attach, killManage background runs
seshat versionPrint the version

Chat

seshat chat                                   # new session
seshat chat --continue                        # resume the most recent session
seshat chat --resume <session-id>             # resume a specific one
seshat chat --model anthropic:claude-sonnet-5-5
seshat chat --permission-mode onRequest
seshat chat --no-tui                          # plain text mode, no full-screen interface

Useful options: --cwd DIR to work in another folder, --db PATH to use another session database, --show-thinking to display the model’s reasoning.

One-shot and background runs

seshat run "summarise the open TODOs in this repository"
seshat run --bg --name nightly-audit "review the last 20 commits for risky changes"

A background run is a local child process. Follow it with the other commands:

seshat ps                          # list background sessions
seshat logs nightly-audit -f       # follow the output (--stream stdout|stderr)
seshat kill nightly-audit          # stop it

Sessions

Sessions are stored in a local SQLite database.

seshat sessions list --status active --n 20
seshat sessions info <id>
seshat sessions delete <id...>        # or --all
seshat sessions prune --older-than 30 --closed

Permission modes

--permission-mode decides who approves the actions of the agent:

ModeBehaviour
onRequestThe default. Seshat asks before actions that need approval
acceptEditsSafe file operations in the working directory are allowed without asking
autoA classifier decides each action. With no classifier configured, Seshat asks you, and in a headless run it refuses
neverNothing is ever asked: a refused action goes back to the model as a failure. For headless and background runs
granularFine-grained control of each approval flow
bypassNo questions. Deny and ask rules, and the safety check, still apply

Providers and models in the interface

Open the providers with ctrl+p, then Providers, then LLM. The list starts with the providers built into Seshat, the ones you have configured marked as such. The last entry, “More providers…”, opens the rest of the models.dev catalog, about 190 providers, with the ones you have configured first. Most of them have not been tried yet, so expect to meet a few rough edges, and tell us about them: the maintainers cannot test every provider, and reports and fixes from the community are how this list gets reliable. You do not have to open that list to find one: type in the search box and every provider is searched, the main ones and the others.

Choosing a provider asks for what it needs. Most take an API key. Codex is a ChatGPT account and has no key: the dialog shows an address and a code, opens your browser by itself, and waits while you enter the code there. The token is kept with its refresh token, and the next start renews it if it has expired. GitHub Copilot signs in with a code in the same way.

The model picker (ctrl+l) lists the models of the providers you have configured, so the list stays short. Until a provider is configured it offers the main providers, so you can set one up.

Shortcuts in the terminal interface

ShortcutAction
ctrl+pSettings and the list of shortcuts
\ at the start of the promptThe palette commands, listed over the prompt: type a few letters to filter, Enter to run. The last entry, “All Commands…”, opens the full dialog
/The skills, listed over the prompt (after a space, or at the start)
@Files and MCP resources to attach (after a space, or at the start)
ctrl+m or ctrl+lModels of the providers you have configured (on terminals that cannot tell ctrl+m from Enter, use ctrl+l)
ctrl+,Providers: the main ones, then “More providers…” for the rest of the catalog
ctrl+sSessions
ctrl+nNew session
ctrl+tShow or hide tasks
ctrl+dShow or hide details
ctrl+yToggle yolo mode
shift+tabEnter or leave plan mode
ctrl+jNew line in the prompt
ctrl+oOpen your editor
ctrl+f, ctrl+vAttach a file, paste an image
ctrl+uCopy the last message
ctrl+gMore help
ctrl+cQuit

Running shell commands from the prompt

A line that starts with ! is a shell command, not a message to the agent. Nothing is sent to the model when you press Enter.

You typeWhat happens
!pip install richThe command runs in the project folder and its output appears in a command panel next to the chat (at the right on a wide screen, under the chat on a narrower one). Scroll it with the mouse wheel. The output is not part of the conversation: it is not stored in the transcript, compacted, read by memory, or paid for in tokens.
!!cat error.logThe same, and the output is also given to the agent: it is placed in front of your next message (cut to its start and end when long), so you do not copy errors by hand.
:!sudo suThe terminal interface steps aside and gives the real terminal to the command until it ends, then comes back. Use it for anything that asks for input: a password, ssh, a shell, an editor.

To give the agent an output you ran with a single !, open the command palette (\ at the start of the prompt) and choose Command Panel: Share Output With the Agent. The same palette has entries to show or hide the panel, to move between the last 20 commands and to clear it.

A ! command has no keyboard input, stops after 5 minutes and keeps the first megabyte of its output. It starts fresh each time, so a cd does not carry over to the next command. A password you type after :! goes straight to the command: the terminal interface never sees it.

Check your setup

seshat doctor          # add --json for machine-readable output

It checks the local configuration, the storage, provider credentials and the helper tools, so it is the first thing to run when something does not work.

Updated on 2026-10-13