Repo initialization

stella works in any directory with no setup. One command gives it a head start by mapping out your codebase:

cd your-project
stella init

What stella init does

1. Guesses the domains in your code → .stella/domains.toml. This is a short list of tags (auth, storage, api, and so on) that labels memories, reflections, and every node in the code graph. It lets the context engine connect a memory, a reflection, and a file that all belong to the same part of your project. It's also saved to .stella/private/context.db.
2. Builds the code graph → .stella/private/codegraph.db. This is an index of your code's symbols and imports. Query it from your shell with stella search instead of guessing with grep.
3. Embeds your files for search by meaning, if you've set up an embedding backend (VOYAGE_API_KEY, OPENAI_API_KEY, or STELLA_EMBED_URL plus STELLA_EMBED_MODEL). This is what lets stella search answer a question like "which file strips secrets before logging" instead of only matching exact text. Without a backend, init says so in one line and skips this step. With one, it tells you how many files it embedded, and how many a large repo left for later, embedding them the first time a search reaches them.
4. Reuses your existing setup. Commands, skills, and agents already defined for other tools — in .claude/ and .agents/ directories, at both workspace and user scope — are linked into .stella/. You keep what you already built instead of starting over.

stella init works offline. With no provider key, it falls back to a simpler guess instead of failing, so you can run it before setting up any key.

What lands where

Everything stella knows about your workspace lives under .stella/. It's all plain files and SQLite databases. Inspect them, put them in version control, or delete them — your choice.

Files to commit

Local state

Never commit these:

If you're upgrading from an older version that wrote files directly under .stella/, stella moves the safe ones into .stella/private/ automatically the first time you run it. If a file has unsafe permissions, or is an active SQLite WAL or SHM file, stella leaves it alone and shows a clear error instead of touching it.

The same kinds of files exist at user scope under ~/.stella/: settings, skills, agents, and credentials.

What to commit

The files listed above under "files to commit" are safe to share with your team and put in version control, with one exception. If .stella/settings.json has an inline api_key, keep that file out of version control. Use api_key_env or credentials.toml instead.

Everything under .stella/private/ is local only, including MCP OAuth tokens. stella writes a .stella/.gitignore for you that covers the private directory, plus any stray database or reflection log left by an older layout:

*.db
*.db-wal
*.db-shm
reflections.jsonl
private/

If your project uses one root .gitignore file instead, add the private directory plus the two extra directories that sit outside it:

.stella/private/
.stella/worktrees/
.stella/exports/

Verify the result

# The index answers structural questions — offline, no API key.
stella search "where is Config defined"
stella search "what imports src/main.rs"

# The taxonomy it inferred.
cat .stella/domains.toml

# The store it will write telemetry into.
stella doctor

# And the resolved provider, model, credential source, and workspace root.
stella config

Run stella init again after a big refactor to rebuild the index and refresh the domain list. It's safe to run more than once, and it works offline: the code graph builds with no provider at all, the domain list falls back to a simple guess based on your folders, and the semantic embedding step just says it was skipped.

Next: set up your provider keys, then run your first task from the quickstart.