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/
1---2name: shellm3description: Reference for the shellm system — recursive LLM shell, identity management, memory, skills, trajectory, and all CLI tools. Use when working on shellm itself, debugging agent behavior, or understanding how the pieces fit together.4---56# shellm78> **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.910## Architecture overview1112shellm is a set of composable bash scripts that turn an LLM into an autonomous agent living in a shell. The stack, bottom to top:1314```15llm raw LLM calls (Anthropic, OpenAI, Gemini)16shellm recursive execute-in-shell loop on top of llm17traj / context step log (DAG) + message assembly for multi-turn18mem / skills persistent memory + learnable capabilities19identity isolated agent identities (own mem, skills, traj)20think / chat autonomous thinking + human conversation21focus goal tracking22```2324An agent activates an identity (`source .identities/<name>/activate`), which sets env vars. All tools read from those env vars — no global config files.2526## bin/ reference2728### Core engine2930| Script | Purpose |31|--------|---------|32| `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. |33| `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`. |3435### Identity & activation3637| Script | Purpose |38|--------|---------|39| `identity` | Manage isolated identities. Each has its own memories, skills, kernel, traj. Subcommands: `new`, `list`, `info`, `switch`, `delete`, `shell`, `prompt`. |4041Activate an identity to set env vars for all other tools:42```bash43source .identities/myagent/activate # activate in current shell44deactivate_identity # undo45identity shell myagent # or: start a subshell46```4748### Thinking & conversation4950| Script | Purpose |51|--------|---------|52| `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]`. |53| `chat` | Send messages into the thought stream. `chat send <msg>` appends a human-msg step. `chat repl` gives a readline loop. |54| `focus` | Goal management. `focus set <goal>`, `focus show`, `focus done <query>`. Stores goals as mem entries with type=goal. |5556### Memory & skills5758| Script | Purpose |59|--------|---------|60| `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>`. |61| `skills` | Skill management. `skills install <src>`, `skills show <name>`, `skills promote <name>` (to kernel), `skills search <query>`, `skills remote add <path>`. |6263### Trajectory & context6465| Script | Purpose |66|--------|---------|67| `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. |68| `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>`. |6970### File utilities7172| Script | Purpose |73|--------|---------|74| `view` | Read files with line numbers. `view FILE [START[:END]]`. |75| `glob` | Git-aware glob matching sorted by mtime. `glob PATTERN [DIR] [--limit N]`. |76| `sub` | Exact-string substitution in files. `sub FILE OLD NEW [--replace-all]`. |77| `put` | Atomic file write from stdin. `echo content \| put FILE [--force]`. |7879### Docker sandboxing8081| Script | Purpose |82|--------|---------|83| `shellm-docker` | Constrained Docker facade for sandboxed execution. `run`, `build`, `ps`, `logs`, `rm`. |84| `shellm-docker-broker` | Host-side broker that manages Docker containers for sandboxed shellm envs. |85| `shellm-explore` | (Not covered here — run exploration tool.) |8687## Key environment variables8889These are set by `source .identities/<name>/activate`:9091| Variable | Points to |92|----------|-----------|93| `IDENTITY_NAME` | Identity name (e.g. "andy") |94| `IDENTITY_DIR` | Identity root dir (e.g. `.identities/andy`) |95| `MEM_DIR` | `$IDENTITY_DIR/memories` |96| `SKILLS_DIR` | `$IDENTITY_DIR/skills` |97| `SKILLS_KERNEL_DIR` | `$IDENTITY_DIR/kernel` |98| `TRAJ_DIR` | `$IDENTITY_DIR/trajectories` |99| `TRAJ_ID` | UUID of root trajectory |100| `SHELLM_TRAJ_DIR` | Trajectory directory (default `$HOME/.shellm/trajectories`) |101| `SHELLM_ENVS_DIR` | Env/container state directory |102| `SHELLM_WORKDIRS_DIR` | Working directories base |103| `SHELLM_BROKER_DIR` | Docker broker state directory |104| `THINK_MODEL` | Model for think cycles |105| `THINK_TICK_INTERVAL` | Seconds between autonomous ticks |106107Other important vars (not identity-scoped):108109| Variable | Purpose |110|----------|---------|111| `SHELLM_MODEL` | Default model for shellm |112| `ANTHROPIC_API_KEY` | Anthropic API key for llm |113| `OPENAI_API_KEY` | OpenAI API key for llm |114115## Identity directory layout116117```118.identities/<name>/119 info.txt name=, cwd=, created=, think_model=, interval=120 activate source-able activation script121 core_identity_prompt.md (optional) custom system prompt122 .env (optional) identity-specific env vars123 memories/ mem entries (markdown files)124 skills/ installed skills125 .skillsrc skill remotes config126 kernel/ kernel skills (always loaded)127 mem/SKILL.md bootstrapped mem skill128 .trajectories/ trajectory files129 trajectory.jsonl main consciousness stream130 blobs/ spilled large fields131 .shellm/ shellm working state132 workdir/ working directory for think cycles133```134135## How a think cycle works1361371. `think step` loads the think prompt template from `$IDENTITY_DIR/prompts/think.md`1382. Replaces `{{identity_name}}` and `{{goals}}` in the template1393. Appends recent traj context (last N steps via `traj tail`)1404. Calls `shellm` with this prompt — shellm executes bash, loops until FINAL1415. Writes the resulting thought or action to traj1426. If it was an action, forks a child branch, executes via shellm, merges back1437. Dispatches thought processes (TPs) — each TP gets recent thoughts and can write to traj/mem144145## Thinkers146147Thinkers live in `thinkers/`. Each has a `step` script, `prompt.md`, and `subscriptions.jsonl`. They subscribe to trajectory events and run autonomously via `thinkers start`:148149- **main** — core thought generator, produces stream-of-consciousness thoughts and actions150- **intentions-goals-creator** — notices emerging goals, stores via mem151- **intentions-goals-enforcer** — redirects when the stream drifts from goals152- **learning** — extracts lessons from action/observation pairs153- **mind-wandering** — surfaces associative memories154- **system-architecture** — meta-cognitive self-modification155- **values-beliefs-creator** — crystallizes values and beliefs156- **values-beliefs-enforcer** — flags misalignment between behavior and values157158## Tips159160- All tools are designed to be composed via pipes and env vars161- `shellm` is the only script that calls the LLM directly (via `llm`); everything else builds prompts and calls `shellm`162- The `context` script is the bridge between traj (step log) and llm (messages array)163- Skills are loaded on-demand via `skills show <name>`; kernel skills are always in context164- To understand any script's full interface, run it with `--help` or read the source in `bin/`
laude-institute