SPRUCE GROVE OS
gran · lund · sv. · spruce grove — an agentic coding CLI grown in the grove.
Together we are better. Always.
Spruce Grove OS is a full custom instance of an agentic coding assistant: the same engine, frameworks, plugins, agents, tools, skills, MCP plumbing, and TUI as the project it is inspired by — replanted around one grove's vision, mission, and values.
Inspired by Code Puppy
Every trail in this grove started as a Code Puppy trail. Spruce Grove OS is built directly from — and stays import-compatible with — Code Puppy by Michael Pfaffenberger (MIT licensed — its notice is preserved verbatim in our NOTICE). Huge respect to the original project and its contributors; this grove exists because the puppy shared everything. Exact lineage, sync points, and the full rename/contract map: PROVENANCE.md.
The ethos of the grove
Four sources, one creed — ETHOS.md:
- Ozark Bagels — how to carry yourself. Be first to say hello. Be kinder than necessary. Be tough minded, but tender hearted. Leave everything better than you found it. Spread joy, love, and cream cheese.
- The Junto (1727) — how to think with others. Love truth for truth's sake. No invented facts — ever; cite or flag "NOT VERIFIED". Provisional phrasing over contradiction combat. Pragmatism over metaphysics.
- gran·lund — who is doing the carrying. Help people solve problems. Remove technology obstacles. Meet people where they are, as humans.
- Wiggledom — how the work moves. Straight lines are brittle; the wiggle is fluid and "stronger than almost anything — like water." Melody is the through-line, rhythm is space and pace, harmony is the relationship between the parts. Embrace the dissonance. When the world feels like a straight line, be a wiggler.
Backed by the Leather Apron Club (Junto)
In 1727 a 21-year-old printer gathered twelve tradesmen in Philadelphia — the Junto, the Leather Apron Club: a mutual-improvement circle that turned Friday-night questions into a subscription library, a fire brigade, and a university. The reboot convenes in Bentonville, Arkansas — first council Friday, September 18, 2026 · Bentonville Barber Company. Spruce Grove OS is the club's shared toolkit: an apprentice that lives on your own machine and works for the town. The standing question is Franklin's own — how can the Junto assist you in any of your honorable designs?
The grove works for the town
No mockups — every showcase below is live today, built by the agent and shipped to a real door:
- tylergranlund.com — the flagship: TanStack Start · React 19 SSR · TypeScript strict · Tailwind v4 · Vitest gates — resale desk, ventures, career, writing, and a colophon that declares its own stack.
- leads.bentondrones.com — lead intake: form → geocode → Jira → dashboard. Python stdlib + SQLite core, Render, Playwright-verified.
- Bentonville Barber Company — the club's home. Victor started it with his family behind him; Drew Garrison and Daniel Devault came along; and when the old landlord hiked the rent, a customer handed the shop its spot on the square. Helping each other — that's the whole thesis. Booking runs on Square; the first council convenes in the chairs.
- sprucegrove.io — the site, the CLI, the desktop shell — all shipped from the same tree.
Meet Cedar
The default agent persona is Cedar, the grove guide — same competent
agent core, new disposition: candid about code, gentle with people, allergic
to invented facts. Rename it anytime in grove.cfg.
Design system
Nordic forest, dark-first. Charcoal base, deep spruce, warm cedar accents, mist typography. Tokens shared with tylergranlund.com — the same palette that colors the terminal splash.
Color tokens
| Token | OKLCH | Role | Chip |
|---|---|---|---|
| charcoal | oklch(0.18 0.012 150) |
base background |  |
| spruce-deep | oklch(0.22 0.03 158) |
deep brand layer |  |
| spruce | oklch(0.32 0.045 158) |
primary brand |  |
| moss | oklch(0.45 0.06 155) |
accent green |  |
| cedar | oklch(0.78 0.12 55) |
warm accent, persona |  |
| bark | oklch(0.32 0.025 60) |
earthy neutral |  |
| stone | oklch(0.85 0.012 90) |
soft UI text |  |
| mist | oklch(0.94 0.008 100) |
foreground/typography |  |
Typography
- Fraunces (variable serif) — wordmarks and display
- Inter — body copy
- JetBrains Mono — code, CLI output
Terminal theming
The boot splash renders a shimmering pyramid + a braille wordmark
("SPRUCE GROVE", compact "GROVE" on narrow terminals) in a truecolor
canopy-to-cedar gradient: halo #2D4F3A → glow #588F5E → core #D2A069,
with a mist-white crest (#F0E1C8) where the sheen passes. ANSI fallbacks
step down through green → bright green → yellow.
Voice
Plain-spoken, warm, a little playful. First to say hello. Candid, never roasty. Zero invented facts — "NOT VERIFIED" beats a confident guess.
Full tokens and voice guide: BRAND.md.
What's inside (same bones as Code Puppy)
┌──────────────────────────────────────────────────┐
│ TUI / CLI (command_line/) │
├──────────────────────────────────────────────────┤
│ Agent Layer (agents/) — Cedar default + JSON │
├──────────────────────────────────────────────────┤
│ Tool Layer (tools/) — TOOL_REGISTRY │
├──────────────────────────────────────────────────┤
│ Plugin Layer (plugins/, callbacks.py) │
├──────────────────────────────────────────────────┤
│ Model Layer (model_factory.py) │
├──────────────────────────────────────────────────┤
│ pydantic-ai + MCP (external) │
└──────────────────────────────────────────────────┘
Python 3.11–3.14 · pydantic-ai · pluggable models (OpenAI, Anthropic, Gemini, Bedrock, Z.AI, custom endpoints) · MCP servers · skills with namespaces · session history + compaction · i18n.
Install & run
git clone https://github.com/t-granlund/SPRUCE-GROVE-OS
cd SPRUCE-GROVE-OS
uv sync
uv run spruce-grove # or: uv run grove
Config: ~/.spruce_grove/grove.cfg · Env vars: SPRUCE_GROVE_*.
Staying current (self-healing updates)
Run it as a uv tool and the grove tends itself:
uv tool install spruce-grove
grove # or: spruce-grove
On every startup a background check compares your install against PyPI. When a newer release exists, the on-disk install upgrades in place while your current session keeps running its warm, consistent code — nothing is restarted, nothing breaks. Your next launch boots the new version, and a single log line tells you the handoff happened. There is no update button to remember, no changelog you must babysit.
NO_AUTO_UPDATE=1— keep the check, never actuateNO_VERSION_UPDATE=1— silence the whole check- Pin back anytime:
uv tool install spruce-grove==X.Y.Z - Source checkouts (the
git cloneflow above) are never touched by the updater — dev environments are sacred.
Details: docs/SELF-UPDATE.md.
Code Puppy compatibility
code_puppy.*imports (e.g. fromcode-puppy-core-plugins) resolve tospruce_grove.*via an import shim with true module identity.- The plugin entry-point group
code_puppy.pluginsis intentionally retained. - Legacy aliases kept:
agent_code_puppy,CodePuppyAgent,get_puppy_name(), persistedpuppy_namefallback. - Full contract ledger: PROVENANCE.md.
License
Apache-2.0 since September 2026 (previously MIT, inherited from Code Puppy). The Code Puppy lineage is preserved verbatim in NOTICE — the puppy came first, and the receipt travels with the work. See also TRADEMARKS.md and PROVENANCE.md.
1 maintainer
Release files for spruce-grove 1.0.83
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spruce_grove-1.0.83.tar.gz | 933.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spruce_grove-1.0.83-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.1 MB
Release files / spruce_grove-1.0.83.tar.gz
| Download URL | spruce_grove-1.0.83.tar.gz |
|---|---|
| Size | 933.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99567aff00acfda9f57ac4a825f66c25166df10486057eb81c44f49c9ca65e92
|
|
BLAKE2b-256 checksum How to use checksums |
ef051464167dbd2d5ba656c5a17d873f87133f8d090b1d64c67b0c97bda55d33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / spruce_grove-1.0.83-py3-none-any.whl
| Download URL | spruce_grove-1.0.83-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7360538298209591dbf77c8eca784645b3eb1985c892bdfa18624474c94bf5cf
|
|
BLAKE2b-256 checksum How to use checksums |
83b9eac0970b24ae3b252dec960b5cae97fa2f6b83501c26ce825eb9b7ec9797
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
