Templates & Satellite Repos

A template is a bootstrap script + initial file set that materializes a Workspace of a particular shape. Pick a template in the Web UI's Workspaces activity, give the workspace a tag, and the template's bootstrap.sh runs to lay down the directory.

Templates are how OpenAlice's ecosystem grows without bloating the main repo: new capabilities (research toolkits, backtest harnesses, custom MCP servers) ship as their own satellite repos that a template clones at bootstrap time.

Anatomy of a template

src/workspaces/templates/<name>/
├── template.json       # metadata (displayName, groupOrder, defaultAgents, ...)
├── bootstrap.sh        # the script that materializes a new workspace
└── files/              # static assets the script copies (optional)
    ├── CLAUDE.md
    ├── mcp.json
    └── ...

template.json keys:

Key	Purpose
`displayName`	Human-readable label in the UI
`description`	Surfaces in the create dialog
`groupOrder`	Sort order in the dashboard's grouped view
`defaultAgents`	Agents pre-checked in the create form (e.g. `["claude", "codex"]`)

bootstrap.sh is the contract. It receives $1 = tag, $2 = outDir, plus a few environment variables (AQ_TEMPLATE_FILES_DIR, AQ_LAUNCHER_REPO_ROOT, optional AQ_LAUNCHER_ROOT defaulting to ~/.openalice/workspaces) and produces a ready-to-use workspace directory. It's bash, so it runs on macOS, Linux, and Windows via Git for Windows / WSL2 — see Workspaces — Windows requirements.

Built-in templates

`chat`

The minimal workspace: an empty git directory wired to OpenAlice's MCP servers, with Alice's persona dropped in as both CLAUDE.md (Claude Code's convention) and AGENTS.md (Codex / general convention), so whichever agent the user picks boots already "as Alice."

Defaults: claude, codex enabled. The chat workspace is what you reach for when you want Alice with full tools but no other scaffolding — research, ad-hoc analysis, exploratory questions.

`auto-quant`

Auto-Quant autoresearch workspace. On first use, clones the public Auto-Quant repo to a shared mirror at ~/.openalice/workspaces/auto-quant-mirror/. Each new workspace then makes a per-workspace local clone with an autoresearch/<tag> branch and symlinked .feather data — so 50 parallel workspaces don't mean 50 copies of the dataset on disk.

Override the source location via AQ_TEMPLATE_DIR if you want to point at a local checkout.

`finance-research`

Bundles himself65/finance-skills — yfinance market data, valuation, earnings, social readers, sentiment. SKILL.md files are copied into project-local .claude/skills/ and .agents/skills/ so both Claude Code and Codex discover them natively.

Cloned fresh from upstream on each workspace creation; the user's global state stays untouched. Defaults: claude, codex enabled.

Satellite-repo pattern

OpenAlice's main repo deliberately doesn't accept ecosystem PRs — it owns the Trading domain and the workspace launcher; everything else routes through satellite repos.

main repo (OpenAlice)              satellite repo (your toolkit)
├── src/                           ├── README.md
│   ├── domain/trading/           ├── tools/
│   ├── core/                     ├── data/
│   └── workspaces/               └── (optional) MCP server
│       └── templates/
│           └── <yours>/
│               ├── template.json
│               ├── bootstrap.sh   ← clones your satellite repo
│               └── files/

Why split:

Template authors ship on their own cadence. No PR queue, no review cycle gated on the main repo.
OpenAlice's src/ stays small. Trading domain + workspace launcher is the focus; ecosystem code doesn't compile-in.
Versioning is per-toolkit. A satellite repo can pin to a specific shape of the data, refactor its internals, or even change languages, without affecting OpenAlice or other satellites.
Provenance is obvious. The bootstrap script's git clone <url> line tells the user where the workspace's code came from. No hidden dependency on a vendored copy.

auto-quant and finance-research are the first two examples — both clone an external repository at bootstrap, both keep their own state, both can be replaced or extended without touching src/.

Writing a new template

Three steps:

Create the directory at src/workspaces/templates/<name>/ with template.json + bootstrap.sh. Optional files/ for static assets.
Write the bootstrap. Source _common.sh for the helpers that handle git init, MCP config writing, and persona composition — most templates only need a few extra steps on top.
Restart OpenAlice. Templates are discovered at startup via TemplateRegistry.load() and cached for the server's lifetime. The new template appears in the Workspaces create dialog.

Keep the bootstrap script POSIX-friendly. Anything that ships with Git for Windows's bundled MSYS env (sed, cp, mkdir, basename, printf, source, [[ ]]) is fine; obscure tools like jq are not — they're not present on Windows users' machines by default.

If your template depends on a sizeable external repo (data, models, a build artifact), use the satellite-repo pattern: keep that repo separate, have bootstrap.sh clone it. Don't vendor it into the OpenAlice main repo.

Search Documentation