Example ways to use Stella — the open-source, BYOK, no-phone-home coding agent that runs in your terminal.
This repo is a working cookbook for everything configurable in Stella: settings profiles, lifecycle hooks, custom agents, custom commands, custom script tools, skills, permission rules, MCP servers, fleet plans, memory taxonomies, and headless scripting. Every file matches the schemas Stella actually parses, and every directory README says where the file goes on disk and what it does once it's there.
- Website / docs: stella.oxagen.sh
- Showcase: these examples are indexed in the Stella showcase
- Install Stella:
curl -fsSL https://raw.githubusercontent.com/macanderson/stella/main/install.sh | sh
| Directory | Surface | Goes in |
|---|---|---|
settings/ |
settings.json profiles — model lineups, providers, local models, team config |
~/.config/stella/settings.json or <repo>/.stella/settings.json |
hooks/ |
Lifecycle hooks — SessionStart, PreToolUse, PostToolUse + guard scripts |
hooks key in settings.json |
commands/ |
Custom slash commands (/fix-issue 42) |
.stella/commands/ or ~/.config/stella/commands/ |
agents/ |
Custom agents with scoped toolbelts (/code-reviewer …) |
.stella/agents/ or ~/.config/stella/agents/ |
skills/ |
Reusable skill documents | .stella/skills/<slug>/SKILL.md |
rules/ |
Workspace rules — soft conventions and hard permission guards | .stella/rules/ or ~/.config/stella/rules/ |
tools/ |
Custom script tools (TOML manifest + executable) | .stella/tools/*.toml or ~/.config/stella/tools/*.toml |
mcp/ |
MCP server config — stdio and HTTP transports | .stella/mcp.toml |
fleet/ |
Fleet plan files — task DAGs fanned out to parallel workers | anywhere; stella fleet --plan <file> |
memory/ |
Memory & domain taxonomy — domains.toml, memories, promotion loop |
.stella/ |
scripting/ |
Headless & CI usage — budgets, JSON output, test-command oracles | your CI / shell |
Most files copy straight into place. The two locations that matter:
- User scope —
~/.config/stella/applies to every project on your machine (settings.json,commands/,agents/,skills/,rules/,tools/). - Project scope —
<repo>/.stella/ships with a repository and applies there (highest precedence in the merge).
One deliberate speed bump: project-scope hooks and credential-routing
fields don't load from a cloned repo until you set STELLA_TRUST_PROJECT=1.
That's Stella refusing to let a repo you just cloned run arbitrary commands
on your machine. Everything cosmetic (display names, default models, custom
commands/agents) applies without it.
# try a profile
cp settings/balanced.settings.json ~/.config/stella/settings.json
# give this repo a custom command
mkdir -p .stella/commands && cp commands/fix-issue.md .stella/commands/
# validate custom tools after copying them
stella tools --validateHave a hook, agent, plan, or profile worth showcasing? PRs welcome — keep each example small, self-contained, and true to the schema Stella parses (cite the docs page it demonstrates). Real-world workflows beat toys.
MIT. Stella itself is dual-licensed MIT OR Apache-2.0.