Solly

Solly is a persistent, provider-agnostic AI orchestration layer for software engineering — plan, build, and review workflows that run deterministically wherever possible and call an LLM only for genuine judgment. It is one reusable engine shared across every project you connect it to; each project owns only its own lightweight .solly/ workspace (plans, decisions, reviews, state) — no Solly source code is ever copied into a project.

curl -fsSL https://install.solly.dev | bash

Then, in any project:

cd my-project
solly init
solly status

And later, when a new Solly release exists:

solly update

(Contributing to Solly itself instead of just using it? See "Contributor Installation" below — a different install path from the one above.)

What Solly is

• One engine, many projects. Solly is not tied to any single company or product. It resolves which project you're in, loads only that project's own context, and never mixes state across projects.
• Deterministic first, LLM second. Routing, risk classification, verification, and workspace migration are plain Python — no model calls, no added context. LLM judgment is reserved for planning, implementation, and review, where it's actually needed. See docs/architecture.md.
• Files, not chat history. Plans, build results, reviews, and telemetry are persisted as files under a project's .solly/ workspace (or, for engine-global state, under ~/.solly) — durable across sessions and Solly upgrades, not dependent on conversation memory.
• Today's capability: AI-assisted software engineering via three Claude Code skills — solly-plan, solly-build, solly-review (see integrations/claude-code/skills/; these three currently require a git checkout — see docs/publishing.md for exactly why, and why that's not fixable by Python packaging). The solly CLI itself has no such requirement — a pip/uv tool install has complete, verified runtime behavior on its own (same doc). The CLI in this README is the installation, lifecycle, and workspace-migration foundation the skills (and a future interactive assistant) run on.

User Installation

This is the path for using Solly on your own projects. If you're contributing to Solly's own source instead, skip to "Contributor Installation" below.

Prerequisites

• macOS or Linux (Windows: run inside WSL).
• Nothing else. The installer bootstraps everything it needs — including Python itself, via uv — from a bare machine.

Install

curl -fsSL https://install.solly.dev | bash

This is a small bootstrap script (install.sh in this repository — read it before piping it to bash if you'd like, that's always a reasonable thing to do with any installer). All it does: check the platform, install uv if missing, install or upgrade Solly via uv tool, and verify both uv --version and solly --version actually run. It never touches ~/.solly, any workspace-root .solly/, or any project's .solly/ — only the solly CLI installation itself. Safe to re-run any time; re-running it is also how you update later (see "Updating Solly" below for the single-command version, solly update).

Fallback, if install.solly.dev is unreachable or you'd rather run the underlying command yourself (uv already installed):

uv tool install solly

(GitHub/raw-content hosts occasionally return HTTP 429 under rate limiting — if curl reports that, wait a few seconds and retry, or use the fallback command above, which talks to PyPI instead.)

Verify the install:

solly --version

First-time setup, start to finish

mkdir -p ~/AIWorkspace && cd ~/AIWorkspace
solly workspace init

Workspace root: ~/AIWorkspace
✓ Created .solly/workspace.yaml (name: AIWorkspace)
✓ Registered as "aiworkspace" in the Solly workspace-root registry

This is optional and purely organizational (see "Register a workspace root" below) — Solly does not require it, does not require exactly one per machine, and does not require your projects to live under it. You can register any number of workspace roots at arbitrary absolute paths (~/Work, ~/Personal, /Volumes/Clients, ...); solly workspace list shows every one registered on this machine.

cd Projects/MyProject   # or wherever your project lives
solly init

Registers the project and creates its .solly/ workspace. Optionally associate it with a company (groups it under a shared, cross-project company brain — see "Companies and the Brain" below):

solly init --company acme

solly status

Solly 0.3.0
Project: myproject (acme)
Root: ~/AIWorkspace/Projects/MyProject
Workspace: ~/AIWorkspace/Projects/MyProject/.solly
Workspace root: AIWorkspace (~/AIWorkspace)
Workspace schema version: 2 (current)
Migration required: no
Workspace health: ok
Capabilities: engineering

solly doctor    # read-only diagnostics; add --fix to apply the same safe migration `solly init` runs

Optionally, start the dashboard:

solly dashboard --company acme

opens the Today/Ask Solly/Projects/Decisions/Knowledge dashboard at http://127.0.0.1:8765.

A workspace root registered this way looks like:

~/AIWorkspace/
├── .solly/
├── Solly/
└── Projects/

— but this is a convention, not a requirement. Nothing above enforces this shape; projects scattered across unrelated directories, or a workspace root with a different name entirely, work identically.

Register a workspace root (optional)

If your projects live together under one parent directory (e.g. ~/AIWorkspace, containing Solly/, Legible/, KinderOS/, ...), register that parent as a workspace root once:

cd ~/AIWorkspace
solly workspace init

This creates ~/AIWorkspace/.solly/workspace.yaml — identity metadata only (schema version, name, type). It holds no project or company state; each project inside still gets its own .solly/ via solly init (below), run individually per project. Registering a workspace root is entirely optional and purely informational (solly status/solly workspace status will report which root, if any, contains the current project) — nothing else changes behavior. You can register any number of workspace roots at arbitrary absolute paths (solly workspace list shows them all); Solly never assumes there's exactly one, or that your projects live under any particular directory.

solly workspace list      # every registered workspace root
solly workspace status    # the root containing the current directory, if any

Initialize Solly inside a project

From the project's root directory:

cd my-project
solly init

This creates (or, if .solly/ already exists, safely updates) the project's workspace: .solly/project.yaml (created with defaults derived from the directory name if absent, otherwise left untouched beyond adding any genuinely missing fields), a workspace.json schema-version marker, and the canonical directories described below. It registers the project by name so it can be resolved from anywhere afterward. solly init is always safe to re-run — every step it takes is additive or merge-only; it never overwrites or deletes anything a project already has.

If .solly/ predates workspace versioning (no workspace.json), solly init detects that and migrates it in place through the same versioned migration framework solly update uses — see "Updating Solly does not replace your project's knowledge," below.

Start Solly

solly

Locates the nearest .solly/ workspace (walking up from your current directory), validates it, and confirms Solly is ready for that project. This milestone's solly does not yet run a full interactive assistant — today, use the /solly-plan, /solly-build, and /solly-review Claude Code skills, which already operate on the same .solly/ workspace solly resolves. solly resolving readiness here is deliberate: the interactive assistant becomes this same command's default behavior in a future milestone, without changing how you invoke it.

Companies and the Brain

Above projects sits a company layer: solly company init <slug> creates a company workspace under ~/.solly/companies/<slug>/, with its own isolated knowledge store (one SQLite file per company — cross-company leakage is structurally impossible, not just avoided by convention). A project links to its company via solly init --company <slug>, which additively creates the company workspace too if it doesn't exist yet.

solly company init procore --name Procore
solly company list                  # every company registered on this machine
cd my-related-items-project && solly init --company procore

solly brain add --company procore --type decision \
  --title "External items get a badge" --text "..."

solly dashboard --company procore   # opens the Today/Ask Solly/Projects/
                                     # Decisions/Knowledge dashboard at
                                     # http://127.0.0.1:8765

solly brain add (and the dashboard's "+ Add to Brain") is manual-only for now — Solly never invents company, personal, or project knowledge on its own; you teach it explicitly. Ask Solly currently does real evidence retrieval against what you've added (with an honest "I don't have enough information" when nothing matches) — LLM-based synthesis on top of that evidence is a deliberate fast-follow, not yet wired up.

A project's slug (its identity in the registry, project.yaml, and any brain rows scoped to it) is independent of its directory name — set once at first solly init, from the directory name at that time. To correct it later without touching the directory on disk:

solly project rename relateditems related-items

Updates the registry key, project.yaml's name field, and migrates any brain rows already scoped to the old slug — all in one operation, so the registry and project.yaml never fall out of sync.

To remove a stale registry entry (e.g. a project whose directory no longer exists) without touching anything on disk:

solly project unregister some-old-slug

Refuses by default if the slug still resolves to a live project on disk (.solly/project.yaml present) — pass --force to unregister one anyway. Either way, this only ever removes the registry entry; the project's own files, .solly/ workspace, and company brain data are never touched.

Updating Solly

solly update

is the single supported way to update — run it inside any registered project. It does two things, in order, every time:

1. Upgrades the installed engine. For a normal (non-editable) install, this runs uv tool upgrade solly and then actually executes the newly-installed solly --version to confirm the upgrade didn't just replace files but produced something that still runs — a distinct, explicit "verified" step, not assumed from uv's own exit code alone. For an editable/development install, this step is skipped with a clear message — see "Contributor Installation" below for how a development install updates instead.
2. Migrates the current project's workspace, if its schema is behind the engine's current version — the exact same safe, additive migration solly init runs. This step always runs, for both install modes, immediately after step 1 — so solly update is also the right command to run just to bring a project's .solly/ workspace current, independent of whether the engine itself needed upgrading.

Solly 0.4.0
Project: Procore
✓ Engine updated 0.3.2 → 0.4.0
✓ Verified: installed `solly` executes successfully
✓ Workspace migrated 3 → 4
✓ Existing knowledge preserved
✓ Existing decisions preserved
✓ Validation passed

Procore is ready.

The distribution pipeline this is built on, end to end:

Developer  →  GitHub  →  GitHub Release (tag)  →  PyPI  →  user's `uv tool upgrade solly`

A tagged, published GitHub Release triggers an automated, token-free publish to PyPI (.github/workflows/publish.yml, PyPI Trusted Publishing — see docs/publishing.md for the full pipeline and the one-time PyPI-side setup it depends on). Once a release has gone through that pipeline, uv tool upgrade solly — and therefore solly update and the bootstrap installer above — pulls it from PyPI, the same as any other published Python package. Until the first release has gone through this pipeline, the fallback GitHub install (uv tool install git+https://github.com/creativescastle/solly.git) remains the working path.

Uninstalling Solly

uv tool uninstall solly

Removes the solly CLI itself — nothing else. This deliberately does not touch:

• ~/.solly — the engine-global home (project/workspace-root registries, company brains, telemetry)
• any workspace root's .solly/workspace.yaml
• any project's .solly/ workspace (plans, decisions, reviews, knowledge)

All of that is independent of whether the solly CLI happens to be installed — reinstalling later (curl -fsSL https://install.solly.dev | bash) picks every registered project and company right back up exactly where it left off, with nothing to restore.

If you genuinely want to remove that data too (rare — this is real, non-recoverable project/company history):

rm -rf ~/.solly                        # every company brain, every registry entry
rm -rf /path/to/some-workspace-root/.solly   # one workspace root's identity marker
rm -rf /path/to/some-project/.solly          # one project's plans/decisions/knowledge

None of these are run by uv tool uninstall or by any Solly command — they're listed here only so an intentional full removal doesn't require guessing at paths.

Troubleshooting

• solly: command not found right after installing. A piped curl | bash runs in a subprocess and can't modify your current terminal's PATH — only new terminals pick up shell-profile changes automatically. The installer prints an explicit source $HOME/.local/bin/env line at the end when this applies to your session; run that once, or just open a new terminal tab.
• uv: command not found after the installer claims success. Same cause as above — uv installs to $HOME/.local/bin too. Same fix.
• curl returns HTTP 429. GitHub/raw-content hosts rate-limit anonymous requests occasionally. Wait a few seconds and retry, or use the fallback command: uv tool install solly.
• solly update's engine-upgrade step reports "not verified." The files were replaced but the new solly --version didn't run cleanly — run solly --version yourself to see the actual error (usually a missing new dependency after an interrupted upgrade). Re-running uv tool install --reinstall solly resolves most cases.
• Something looks wrong with a project's workspace. solly doctor is always the first thing to run — read-only diagnostics that never modify anything unless you pass --fix.
• None of the above. solly status and solly doctor's output is safe to share when asking for help — neither ever prints secrets or full config contents, per their own design (see "Check health" below).

Check health

solly status    # concise project/workspace summary — never dumps secrets or config contents
solly doctor     # read-only diagnostics: broken/outdated state, missing files, registry drift
solly doctor --fix   # applies the same safe, additive migration `solly init` does — nothing else

solly doctor never deletes or silently rewrites your data; --fix is the one explicit, opt-in exception, and it only ever runs the same additive migration described below.

What .solly/ contains

.solly/
  project.yaml      identity, capabilities, verification commands (project-owned)
  workspace.json     schema version + migration history (Solly-managed)
  current-state.md    short "where things stand" snapshot
  architecture.md      project-specific constraints Solly should respect
  plans/                 one file per plan (solly-plan)
  tasks/                   one file per build task/result (solly-build)
  reviews/                  one file per review (solly-review)
  decisions/                 decision records — both solly-plan/review's and
                               solly brain add --type decision's write-ups
  knowledge/                  raw files ingested via `solly brain add`
  context/                     reserved
  assistant/                    reserved
  sessions/                      reserved

No Solly engine source code lives here — ever. Telemetry (docs/telemetry.md), the project registry, and a project's company (~/.solly/companies/<slug>/ — see "Companies and the Brain" above) are all engine-global, under ~/.solly (overridable via SOLLY_HOME), not per-project — so a project's .solly/ stays small, portable, and safe to commit to that project's own repository.

Updating Solly does not replace your project's knowledge

This is the single most important guarantee of the update/migration system: solly update and solly init never reset, overwrite, or delete anything already in a project's .solly/ workspace. Every workspace migration (src/solly/workspace/migrations/) is additive by design — it only creates files/directories that don't exist yet, records what it did in workspace.json's migration history, and is safe to interrupt or re-run at any point. Your plans, build results, reviews, decisions, and any files you've added yourself survive indefinitely across Solly upgrades. If a future migration ever needs to transform (not just add) an existing file, it's required to write a recovery copy first and to fail loudly rather than risk data it can't guarantee it preserved.

Contributor Installation

This is the path for working on Solly's own source — not for using Solly on your other projects (see "User Installation" above for that).

git clone https://github.com/creativescastle/solly.git Solly
cd Solly
uv tool install --editable .

This installs the same solly console script, but backed by your local checkout — edits to the checkout take effect immediately, without reinstalling. An editable install never pulls from PyPI or GitHub — it only ever reflects whatever is currently on disk in that checkout. git pull in the checkout is how a development install "updates"; see "Updating Solly" above for exactly how solly update treats an editable install differently (it skips the engine-upgrade step with a clear message, rather than pretending to upgrade something that has no "latest release" to move to). If the pulled commits changed pyproject.toml's dependencies or added a new top-level package, git pull alone won't reflect that — rerun uv tool install --reinstall --editable . as well.

The install mechanism is intentionally isolated behind one small module (src/solly/cli/engine_upgrade.py) precisely so the installation source — GitHub, PyPI, editable for contributors — never requires touching workspace/migration logic.

Running the test suite

git clone https://github.com/creativescastle/solly.git Solly
cd Solly
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python -m unittest discover -s tests -t .

The package must be installed (editable is fine) before running the test suite — tests/ imports solly.* as a real installed package, not via a sys.path trick. tests/__init__.py isolates SOLLY_HOME and SOLLY_TELEMETRY_PATH to throwaway temp directories for the whole test session, so running tests never touches a real installation's ~/.solly.

uv run pytest is the equivalent one-liner if you're using uv for the whole workflow (uv sync first to pick up the dev dependency group).

See CLAUDE.md for the full architecture and operating rules, and docs/architecture.md / docs/project-integration.md / docs/publishing.md / docs/telemetry.md for the deeper documentation this README intentionally stays short and points to rather than duplicating.

Versioning

Several independent version numbers, each tracking a different thing and bumped separately — an application release doesn't imply any of the others changed:

• Solly application version (solly --version, pyproject.toml's [project].version) — bumps on engine/CLI releases.
• Project workspace schema version (solly status, .solly/workspace.json) — bumps only when a project's .solly/ structure changes (src/solly/workspace/schema.py).
• Company workspace schema version (~/.solly/companies/<slug>/company.yaml) — bumps only when the company workspace structure changes (src/solly/company/schema.py).
• Brain schema version (brain.db's internal brain_meta table) — bumps only when the Source/Decision/ContextEntry table shapes change (src/solly/brain/schema.py).

Releases are tagged semantic versions (vX.Y.Z) against this repository's GitHub remote and published to PyPI from that tag (see "Updating Solly" above, docs/publishing.md); solly --version is always the authoritative, programmatically-checkable answer for which engine version is installed.