shellm
This skill may be out of date. The source of truth is always the code in bin/. If you find discrepancies, use the skill-author skill to update this file and open a PR.
Architecture overview
shellm is a set of composable bash scripts that turn an LLM into an autonomous agent living in a shell. The stack, bottom to top:
llm raw LLM calls (Anthropic, OpenAI, Gemini)
shellm recursive execute-in-shell loop on top of llm
traj / context step log (DAG) + message assembly for multi-turn
mem / skills persistent memory + learnable capabilities
identity isolated agent identities (own mem, skills, traj)
think / chat autonomous thinking + human conversation
focus goal tracking
An agent activates an identity (source .identities/<name>/activate), which sets env vars. All tools read from those env vars — no global config files.
bin/ reference
Core engine
| Script |
Purpose |
shellm |
Recursive LLM-in-bash loop. Sends a prompt to the LLM, executes returned bash code blocks, feeds output back, repeats until FINAL is set. The heart of the system. |
llm |
Multi-provider LLM CLI. llm [options] prompt or stdin. Supports Anthropic, OpenAI, Gemini. Key flags: -m MODEL, -s SYSTEM, -M MESSAGES_JSON, --stream, --thinking. |
Identity & activation
| Script |
Purpose |
identity |
Manage isolated identities. Each has its own memories, skills, kernel, traj. Subcommands: new, list, info, switch, delete, shell, prompt. |
Activate an identity to set env vars for all other tools:
source .identities/myagent/activate # activate in current shell
deactivate_identity # undo
identity shell myagent # or: start a subshell
Thinking & conversation
| Script |
Purpose |
think |
One autonomous think cycle. Reads traj + memories, calls shellm with think prompt, writes thought/action to traj, dispatches thought processes. think step [--dry-run]. |
chat |
Send messages into the thought stream. chat send <msg> appends a human-msg step. chat repl gives a readline loop. |
focus |
Goal management. focus set <goal>, focus show, focus done <query>. Stores goals as mem entries with type=goal. |
Memory & skills
| Script |
Purpose |
mem |
File-based memory store (markdown + YAML frontmatter). mem add --type TYPE <text>, mem search <query>, mem list, mem show <name>, mem forget <name>, mem edit <name> <text>. |
skills |
Skill management. skills install <src>, skills show <name>, skills promote <name> (to kernel), skills search <query>, skills remote add <path>. |
Trajectory & context
| Script |
Purpose |
traj |
Trajectory operations (single-file and tree). Uses TRAJ_DIR + TRAJ_ID. traj new, traj append, traj tail, traj cat, traj fork, traj merge, traj show, traj list, traj root. show is unified: pass any ID (trajectory or step) and it searches all files in traj_dir. |
context |
Reads traj, outputs a JSON messages array for llm -M. Maps step types to assistant/user roles. Key flags: --traj_dir, --tail N, --head N, --max-bytes, --pin <step_id>. |
File utilities
| Script |
Purpose |
view |
Read files with line numbers. view FILE [START[:END]]. |
glob |
Git-aware glob matching sorted by mtime. glob PATTERN [DIR] [--limit N]. |
sub |
Exact-string substitution in files. sub FILE OLD NEW [--replace-all]. |
put |
Atomic file write from stdin. echo content | put FILE [--force]. |
Docker sandboxing
| Script |
Purpose |
shellm-docker |
Constrained Docker facade for sandboxed execution. run, build, ps, logs, rm. |
shellm-docker-broker |
Host-side broker that manages Docker containers for sandboxed shellm envs. |
shellm-explore |
(Not covered here — run exploration tool.) |
Key environment variables
These are set by source .identities/<name>/activate:
| Variable |
Points to |
IDENTITY_NAME |
Identity name (e.g. "andy") |
IDENTITY_DIR |
Identity root dir (e.g. .identities/andy) |
MEM_DIR |
$IDENTITY_DIR/memories |
SKILLS_DIR |
$IDENTITY_DIR/skills |
SKILLS_KERNEL_DIR |
$IDENTITY_DIR/kernel |
TRAJ_DIR |
$IDENTITY_DIR/trajectories |
TRAJ_ID |
UUID of root trajectory |
SHELLM_TRAJ_DIR |
Trajectory directory (default $HOME/.shellm/trajectories) |
SHELLM_ENVS_DIR |
Env/container state directory |
SHELLM_WORKDIRS_DIR |
Working directories base |
SHELLM_BROKER_DIR |
Docker broker state directory |
THINK_MODEL |
Model for think cycles |
THINK_TICK_INTERVAL |
Seconds between autonomous ticks |
Other important vars (not identity-scoped):
| Variable |
Purpose |
SHELLM_MODEL |
Default model for shellm |
ANTHROPIC_API_KEY |
Anthropic API key for llm |
OPENAI_API_KEY |
OpenAI API key for llm |
Identity directory layout
.identities/<name>/
info.txt name=, cwd=, created=, think_model=, interval=
activate source-able activation script
core_identity_prompt.md (optional) custom system prompt
.env (optional) identity-specific env vars
memories/ mem entries (markdown files)
skills/ installed skills
.skillsrc skill remotes config
kernel/ kernel skills (always loaded)
mem/SKILL.md bootstrapped mem skill
.trajectories/ trajectory files
trajectory.jsonl main consciousness stream
blobs/ spilled large fields
.shellm/ shellm working state
workdir/ working directory for think cycles
How a think cycle works
think step loads the think prompt template from $IDENTITY_DIR/prompts/think.md- Replaces
{{identity_name}} and {{goals}} in the template
- Appends recent traj context (last N steps via
traj tail)
- Calls
shellm with this prompt — shellm executes bash, loops until FINAL
- Writes the resulting thought or action to traj
- If it was an action, forks a child branch, executes via shellm, merges back
- Dispatches thought processes (TPs) — each TP gets recent thoughts and can write to traj/mem
Thinkers
Thinkers live in thinkers/. Each has a step script, prompt.md, and subscriptions.jsonl. They subscribe to trajectory events and run autonomously via thinkers start:
- main — core thought generator, produces stream-of-consciousness thoughts and actions
- intentions-goals-creator — notices emerging goals, stores via mem
- intentions-goals-enforcer — redirects when the stream drifts from goals
- learning — extracts lessons from action/observation pairs
- mind-wandering — surfaces associative memories
- system-architecture — meta-cognitive self-modification
- values-beliefs-creator — crystallizes values and beliefs
- values-beliefs-enforcer — flags misalignment between behavior and values
Tips
- All tools are designed to be composed via pipes and env vars
shellm is the only script that calls the LLM directly (via llm); everything else builds prompts and calls shellm- The
context script is the bridge between traj (step log) and llm (messages array)
- Skills are loaded on-demand via
skills show <name>; kernel skills are always in context
- To understand any script's full interface, run it with
--help or read the source in bin/
