Metadata-Version: 2.5
Name: spruce-grove
Version: 1.0.7
Summary: Spruce Grove OS - an agentic coding CLI distribution inspired by Code Puppy. Together we are better. Always.
Project-URL: repository, https://github.com/t-granlund/SPRUCE-GROVE-OS
Project-URL: HomePage, https://tylergranlund.com
Author: Michael Pfaffenberger
Author-email: Tyler Granlund <hello@tylergranlund.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: <3.15,>=3.11
Requires-Dist: agent-client-protocol<0.12,>=0.11.0
Requires-Dist: anthropic<2,>=1.0.0
Requires-Dist: anyio>=4.7.0
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: boto3>=1.43.9
Requires-Dist: code-puppy-core-plugins>=0.0.45
Requires-Dist: httpx2>=2.7
Requires-Dist: httpx[http2]>=0.24.1
Requires-Dist: json-repair>=0.46.2
Requires-Dist: keyring>=24.0.0
Requires-Dist: logfire>=4.0
Requires-Dist: mcp>=1.9.4
Requires-Dist: openai>=2.45.0
Requires-Dist: packaging>=24.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright>=1.40.0; sys_platform != 'android'
Requires-Dist: pydantic-ai-harness==0.23.0
Requires-Dist: pydantic-ai-slim[anthropic,mcp,openai]==2.35.0
Requires-Dist: pydantic>=2.4.0
Requires-Dist: pyfiglet>=0.8.post1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rapidfuzz>=3.13.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.4.2
Requires-Dist: ripgrep==14.1.0; sys_platform != 'android'
Requires-Dist: termflow-md>=0.9.1
Requires-Dist: typer>=0.12.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.35.0; extra == 'bedrock'
Provides-Extra: computer-use
Requires-Dist: pyobjc-framework-applicationservices>=10.3; (sys_platform == 'darwin') and extra == 'computer-use'
Requires-Dist: pyobjc-framework-cocoa>=10.3; (sys_platform == 'darwin') and extra == 'computer-use'
Requires-Dist: pyobjc-framework-quartz>=10.3; (sys_platform == 'darwin') and extra == 'computer-use'
Provides-Extra: durable
Requires-Dist: dbos>=2.11.0; extra == 'durable'
Description-Content-Type: text/markdown

# SPRUCE GROVE OS

<p align="center">
  <img src="logos/spruce_grove_logo_withback.jpeg" alt="The Spruce Grove mark - three geometric spruces in brand greens on charcoal" width="260">
</p>

**gran · lund · sv. · spruce grove** — an agentic coding CLI grown in the grove.

> Together we are better. Always.

![License: MIT](https://img.shields.io/badge/license-MIT-2D4F3A)
![Python 3.11–3.14](https://img.shields.io/badge/python-3.11--3.14-588F5E)
![Tests: 7700 passing](https://img.shields.io/badge/tests-7700%20passing-D2A069)
![Inspired by Code Puppy](https://img.shields.io/badge/inspired%20by-Code%20Puppy-F0E1C8)

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](https://github.com/mpfaffenberger/code_puppy)
(MIT licensed). 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](PROVENANCE.md).

## The ethos of the grove

Three sources, one creed — [ETHOS.md](ETHOS.md):

1. **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.
2. **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.
3. **gran·lund — who is doing the carrying.** Help people solve problems.
   Remove technology obstacles. Meet people where they are, as humans.

## 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](https://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 | ![#1d211e](https://img.shields.io/badge/-%23001D21-1d211e) |
| spruce-deep | `oklch(0.22 0.03 158)` | deep brand layer | ![#20392b](https://img.shields.io/badge/-%2320392B-20392b) |
| spruce | `oklch(0.32 0.045 158)` | primary brand | ![#2d4f3a](https://img.shields.io/badge/-%232D4F3A-2d4f3a) |
| moss | `oklch(0.45 0.06 155)` | accent green | ![#588f5e](https://img.shields.io/badge/-%23588F5E-588f5e) |
| cedar | `oklch(0.78 0.12 55)` | warm accent, persona | ![#d2a069](https://img.shields.io/badge/-%23D2A069-d2a069) |
| bark | `oklch(0.32 0.025 60)` | earthy neutral | ![#4d4136](https://img.shields.io/badge/-%234D4136-4d4136) |
| stone | `oklch(0.85 0.012 90)` | soft UI text | ![#d6d2c8](https://img.shields.io/badge/-%23D6D2C8-d6d2c8) |
| mist | `oklch(0.94 0.008 100)` | foreground/typography | ![#f0e1c8](https://img.shields.io/badge/-%23F0E1C8-f0e1c8) |

### Typography

- **Fraunces** (variable serif) — wordmarks and display
- **Inter** — body copy
- **JetBrains Mono** — code, CLI output

### Terminal theming

The boot splash renders a shimmering pyramid + figlet lockup
("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](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

```bash
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_*`.

## Code Puppy compatibility

- `code_puppy.*` imports (e.g. from `code-puppy-core-plugins`) resolve to
  `spruce_grove.*` via an import shim with true module identity.
- The plugin entry-point group `code_puppy.plugins` is intentionally retained.
- Legacy aliases kept: `agent_code_puppy`, `CodePuppyAgent`,
  `get_puppy_name()`, persisted `puppy_name` fallback.
- Full contract ledger: [PROVENANCE.md](PROVENANCE.md).

## License

MIT — inherited from Code Puppy. See [LICENSE](LICENSE) and attribution in
[PROVENANCE.md](PROVENANCE.md).
