Repo initialization
Prime a workspace with stella init — the domain taxonomy, the tree-sitter code graph, extension adoption, and everything that lands under .stella/.
Stella works in any directory with zero setup — but one command primes it with structured knowledge of your codebase:
cd your-project
stella initWhat stella init does
- Infers the domain taxonomy →
.stella/domains.toml. A short, shared tagging vocabulary (auth, storage, api, …) used to label memories, reflections, and every code-graph node — so the context engine can relate a memory, a reflection, and a file to the same area of your project. Also persisted into the context plane at.stella/context.db. - Builds the code-graph index →
.stella/codegraph.db. A tree-sitter symbol/import index the agent queries throughgraph_query(and you query throughstella graph) instead of grepping blind. - Adopts existing agent extensions. Commands, skills, and agents already
defined for other tools (
.claude/and.agents/directories, workspace and user scope) are adopted as symlinks under.stella/— your existing setup carries over instead of starting from scratch.
stella init works offline with a heuristic fallback, so it never
hard-fails: you can initialize before configuring any provider key.
In interactive sessions the graph also auto-builds in the background and
refreshes live as files change — stella init is about doing it once,
eagerly, and generating the taxonomy alongside. Re-run it after large
refactors to rebuild the index and re-infer the taxonomy.
What lands where
Everything Stella knows about a workspace lives under .stella/ — plain
files and SQLite databases you can inspect, version, or delete at will:
| Path | What it holds |
|---|---|
.stella/domains.toml | The domain taxonomy (tagging vocabulary) |
.stella/codegraph.db | The tree-sitter code-graph index |
.stella/context.db | The context plane — memory nodes, reflections, episodes, bi-temporal facts |
.stella/store.db | Executions, events, token/cost telemetry, the files-touched ledger |
.stella/memories/*.md | Workspace memories (plain Markdown) |
.stella/rules/*.md | Workspace rules — promoted memories and guard rules |
.stella/skills/ | Project-scope skills |
.stella/settings.json | Project-scope settings |
.stella/mcp.toml | MCP servers to connect at session start |
.stella/tools/*.toml | Custom script tools |
.stella/commands/ · .stella/agents/ | Custom commands and custom agents |
.stella/fleet.db | The fleet ledger — runs, attempts, commits |
.stella/worktrees/ | Dedicated worktrees for fleet tasks marked isolation = "isolated" |
.stella/exports/ | Session telemetry exports (ZIP + HTML) |
.stella/reflections.jsonl | Post-turn reflection log (lessons the context engine distills) |
.stella/mcp_oauth.json | OAuth tokens for MCP servers you've logged into — a secret, never commit it |
User-scope counterparts live under ~/.config/stella/ (settings, skills,
agents, credentials).
What to commit
.stella/domains.toml, .stella/memories/, .stella/rules/,
.stella/skills/, .stella/settings.json, .stella/mcp.toml, and
.stella/tools/ are team-shareable and version-control-friendly — with one caveat:
if .stella/settings.json carries an inline api_key, keep it out of version control
(prefer api_key_env or credentials.toml). The
.db files are local state, and .stella/mcp_oauth.json holds OAuth tokens — add
all of them to .gitignore:
.stella/*.db
.stella/*.db-*
.stella/mcp_oauth.json
.stella/worktrees/
.stella/exports/
.stella/reflections.jsonlVerify the result
stella graph definitions <SomeSymbol> # the index answers structural questions
stella config # the resolved provider/model/workspaceNext: configure your provider keys, then run your first task from the quickstart.
Providers & models
The full provider matrix, how to select a model, the credential chain, and pointing Stella at a local OpenAI-compatible server.
API Providers
Every provider Stella speaks to — the full matrix, the auto-detection order, and the credential chain. Bring your own key; Stella talks each provider's native dialect.