@retroghostlabs/bozly

v0.3.0-rc.1

Published

a month ago

Build. Organize. Link. Yield. — AI-agnostic framework for domain-specific workspaces

0High
0Medium
0Low

retroghost

ai cli vault workspace context claude gpt gemini ollama

BOZLY

Build. OrganiZe. Link. Yield.

An AI-agnostic framework for deploying domain-specific workspaces. Use the same architecture patterns as Cursor and Cline, but for any life domain — music, content production, journaling, research, anything.

Why BOZLY?

Everyone's using AI coding assistants like Cursor and Cline for software development. But what about music discovery, content production, life management, or research?

BOZLY applies the same proven architecture patterns to any domain.

What Makes BOZLY Different

| Feature | Code Tools (Cursor/Cline) | BOZLY | |---------|--------------------------|-------| | Domains | Code only | Any domain | | AI Lock-in | Some | None — works with any AI | | Architecture | Proven | Same patterns, new domains | | Storage | Tool-specific | AI-agnostic JSON | | Context | Per-tool | Single source, any AI |

Key Features

AI-Agnostic — Works with Claude, GPT, Gemini, Ollama, any AI CLI
Multi-Vault — Orchestrate multiple domain-specific workspaces
Non-Code Domains — Music, journaling, content production, research
Cline/Cursor Patterns — Task folders, session storage, hooks
Context Provider — BOZLY prepares prompts, your AI executes
Unix-Native — macOS, Linux, WSL2 (no native Windows)

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  USER runs: bozly run daily                                     │
├─────────────────────────────────────────────────────────────────┤
│  BOZLY:                                                         │
│  1. Loads vault context (.bozly/context.md)                     │
│  2. Loads command prompt (.bozly/commands/daily.md)             │
│  3. Combines context + prompt                                   │
│  4. Pipes to AI CLI (claude/gpt/gemini/ollama)                  │
│  5. Saves session to .bozly/sessions/                           │
└─────────────────────────────────────────────────────────────────┘

Key Insight: BOZLY is a "context provider" — it prepares the prompts, your AI executes them.

Architecture

Folder Structure

~/.bozly/                              ← GLOBAL
├── bozly-registry.json                ← All vault locations
├── bozly-config.json                  ← Global settings
├── commands/                          ← Global commands
└── templates/                         ← Starter templates

~/music-vault/.bozly/                  ← PER-VAULT
├── config.json                        ← Vault settings
├── context.md                         ← AI context file
├── index.json                         ← Task index
├── sessions/                          ← Session history
├── tasks/                             ← Task data (Cline-style)
├── commands/                          ← Vault commands
├── workflows/                         ← Multi-step processes
└── hooks/                             ← Automation triggers

Three-Tier Update Safety

TIER 1: BOZLY CORE (Framework-Owned)
└── npm/brew install — BOZLY releases update this

TIER 2: GLOBAL USER CONFIG (User-Owned)
└── ~/.bozly/ — User edits, BOZLY never touches

TIER 3: VAULT CONFIG (Vault-Owned)
└── ~/vault/.bozly/ — User edits, BOZLY never touches

Quick Start

Requirements

macOS, Linux, or WSL2 (no native Windows)
Node.js 18+ (for npm install)
At least one AI CLI installed:
- Claude: npm install -g @anthropic-ai/claude-code
- GPT: pip install openai-cli
- Ollama: brew install ollama

Installation

Beta Status: BOZLY 0.3.0-beta.1 is now available for public beta testing. All Phase 1 features are implemented and tested. Report issues on GitHub.

# npm (recommended - beta version)
npm install -g [email protected]

# Or install latest beta automatically
npm install -g bozly

# Homebrew (coming soon for v1.0)
# brew tap retroghostlabs/bozly
# brew install bozly

# From source
git clone https://github.com/RetroGhostLabs/bozly.git
cd bozly && npm install && npm link

Create Your First Vault

# Create a vault directory
mkdir ~/music-vault
cd ~/music-vault

# Initialize with BOZLY
bozly init --name "Music Discovery" --type music

# Run a command (with --dry to preview first)
bozly run daily --dry              # Preview the prompt
bozly run daily --ai claude        # Execute with Claude

Configure Your AI Provider

BOZLY works with any AI CLI. Check what's available:

# See installed providers
bozly run --list-providers

# Try different providers
bozly run daily --ai claude        # Recommended if you have API key
bozly run daily --ai ollama        # Local/private (download from ollama.ai)
bozly run daily --ai gpt           # OpenAI (requires OPENAI_API_KEY env var)

Full setup guide: See AI-PROVIDERS.md

Example Vaults

BOZLY includes example vaults to get you started:

Music Discovery Vault

Album reviews with custom scoring
TRIPLE search strategy (Influence + Year + All-time)
Weekly album selection
Commands: /daily, /weekly-roll, /complete-album

Journal Vault

Daily entries with mood tracking
Weekly reviews and reflection
Template-based workflows
Commands: /daily-entry, /log-mood, /weekly-review

Content Production Vault

Video production pipeline
Script writing workflows
Multi-camera recording notes
Commands: /new-outline, /write-script, /prep-production

Commands

Vault Management

bozly init                    # Initialize vault in current directory
bozly add <path>              # Register an existing vault
bozly remove <name>           # Remove and optionally backup vault
bozly list                    # List all registered vaults
bozly status                  # Show current vault status

Remove Command Options

bozly remove my-vault                 # Remove vault (with confirmation)
bozly remove my-vault --force          # Skip confirmation prompt
bozly remove my-vault --backup         # Create backup before removing
bozly remove my-vault --keep-files     # Remove from registry only, keep files
bozly remove my-vault --backup --force # Backup + remove without confirmation

Backups are created in ~/.bozly/backups/ with timestamps.

Core Commands

bozly context                 # Generate AI context from vault
bozly run <command>           # Run command with AI
bozly logs                    # View session history
bozly diff                    # Compare session executions
bozly version                 # Show framework version

AI Selection

bozly run daily               # Use default AI
bozly run daily --ai claude   # Use Claude
bozly run daily --ai gpt      # Use GPT
bozly run daily --ai ollama   # Use local Ollama

Configuration

bozly config                  # View all config
bozly config set ai.default claude
bozly config ai add gpt       # Add AI provider

See CLI-DESIGN.md for full command reference.

Tech Stack

| Component | Choice | Rationale | |-----------|--------|-----------| | Language | TypeScript | Matches Cline/Cursor ecosystem | | Storage | JSON files | Simple, debuggable | | AI Support | AI-agnostic | Any CLI: claude, gpt, gemini, ollama | | Platforms | Unix-only | macOS, Linux, WSL2 | | Distribution | npm, Homebrew | Standard package managers |

Project Status

Current Phase: Phase 1: Beta (Release Phase — 94% Complete)

Progress: 17 of 18 sessions complete | Sprint 1-3: ✅ 100% COMPLETE | Sprint 4: 🔄 IN PROGRESS (3 of 4 sessions)

Timeline: Beta ready Early Feb 2026 | v1.0 Public Launch June 2026

Development Progress

Phase 1: Beta (v0.3.0) — Sprint 1-4 (18 sessions, Sessions 37-59)

Sprint 1: Foundation           ✅ 100% COMPLETE (Sessions 37-40)
  ✅ TypeScript CLI structure with 7 commands
  ✅ Core modules: vault, registry, config, context (3,000+ lines)
  ✅ Comprehensive logging system (400+ lines)
  ✅ 4 vault templates + 2 example vaults
  ✅ Unit tests (63 passing)

Sprint 2: Execution            ✅ 100% COMPLETE (Sessions 44-52)
  ✅ Session 44: Context loading & validation (context.ts)
  ✅ Session 45: Domain Models + Commands (models.ts 800+ lines) ⭐
  ✅ Session 46: AI CLI integration (providers.ts, 4 providers)
  ✅ Session 49: Manual framework walkthrough (Part 1)
  ✅ Session 50: Memory systems & n8n research (956 lines)
  ✅ Session 51: Ecosystem research consolidation
  ✅ Session 52: Session recording architecture design (500+ lines)
  ✅ Session 53: Session recording implementation (NEXT)
  Target: `bozly run daily` fully functional with session recording + audit trail

Sprint 3: Patterns             ✅ 100% COMPLETE (Sessions 53-55)
  ✅ Session 53: Session recording implementation (Part 2 final)
    ✅ recordSession(), loadSession(), querySessions(), diffSessions()
    ✅ bozly logs + bozly diff commands with filters
    ✅ Session files: multi-file architecture (6 files per session)
    ✅ Session hierarchy: vault/date/id organization
    ✅ 32 unit tests all passing
    ✅ SESSION-RECORDING-GUIDE.md documentation
  ✅ Session 54: Session transparency (Pattern 2) — Global operations
    ✅ querySessionsGlobal(), getSessionStatsGlobal(), archival functions
    ✅ bozly logs --global, --stats flags
    ✅ 6 new functions + 37 tests (6 new patterns tests)
    ✅ Multi-vault session monitoring enabled
  ✅ Session 55: Versioning System (Pattern 4) — Version Management
    ✅ versions.ts module with semantic versioning
    ✅ bozly version command with --vault, --model, --history flags
    ✅ Model version tracking integrated with loadModel()
    ✅ Context version tracking integrated with generateContext()
    ✅ 39 unit tests all passing
    ✅ VERSIONING-GUIDE.md (600+ lines documentation)

Sprint 4: Release              🔄 IN PROGRESS (Sessions 56-59)
  ✅ Session 56: CLAUDE.md Optimization & Timeline Updates (COMPLETE)
  ✅ Session 56b: ESLint Cleanup & vitest 4.0 Upgrade (COMPLETE)
  ✅ Session 57: Manual CLI Testing (COMPLETE - 36 test scenarios)
  ✅ Session 58: Vault Removal + Test Cleanup Infrastructure (COMPLETE)
  ⏳ Session 59: npm Publish & Beta Launch (NEXT)

⭐ Key Completed Work (Sessions 44-52):

Context loading infrastructure + vault context generation
Domain Models (Pattern 7): YAML-based definitions with 4 types (scoring, analysis, classification, prediction)
AI Provider integration: Claude, ChatGPT, Gemini, Ollama detection and streaming execution
Session recording architecture: Multi-file design (6 files/session) with vault/date/id hierarchy
Manual framework validation: All CLI commands tested end-to-end, logger bug fixed
Ecosystem research: Claude memory + n8n integration patterns fully documented (1,500+ lines)
Combined 4,000+ lines of production code + 2,000+ lines of architecture documentation

Phase 2: Polish (v0.4.0-0.5.0) — 6-8 weeks after Phase 1

[ ] Hooks system (session-start, session-end, post-tool)
[ ] Workflows (multi-step processes)
[ ] Cross-vault queries (bozly search --all)
[ ] Session history viewer (bozly history)
[ ] Task tracking (bozly tasks)

Phase 3: Ecosystem (v1.0.0) — 8-12 weeks after Phase 2

[ ] Community vault registry
[ ] bozly search / bozly install
[ ] Vault publishing
[ ] Obsidian plugin (paid)

See ROADMAP.md for full timeline and progress tracking docs.

Documentation

| Document | Purpose | |----------|---------| | GETTING-STARTED.md | First vault setup | | ARCHITECTURE.md | Technical deep dive | | CLI-DESIGN.md | Command reference | | SESSION-RECORDING-GUIDE.md | Session history & audit trail | | BUILDING-YOUR-VAULT.md | Custom vault creation |

Migration from AI Vault Framework

If you used the previous AI Vault Framework (Python/Bash version):

| Old | New | |-----|-----| | ai-vault-framework | bozly | | .claude/ or .ai-vault/ | .bozly/ | | ~/.ai-vault/ | ~/.bozly/ | | Python/Bash scripts | TypeScript CLI | | WORK-LOG.md (manual) | .bozly/sessions/ (automatic) | | CLAUDE.md only | context.md (AI-agnostic) |

Run bozly migrate to convert existing vaults.

Contributing

We welcome contributions:

Report bugs — Open an issue
Share your vault — Create a repo and share in Discussions
Improve docs — Submit a PR for typos or improvements
Contribute code — See CONTRIBUTING.md

License

MIT License — Use it for anything.

See LICENSE for details.

Connect

GitHub: bozly
Discussions: Ask questions & share vaults
Issues: Report bugs & request features

BOZLY: Build. OrganiZe. Link. Yield.

Built by RetroGhostLabs | MIT License

Last updated: 2025-12-21 | Status: Phase 1 Beta (Sprints 1-3 Complete, Sprint 4: 3/4 Sessions) | Progress: 94% | Beta: Early Feb 2026 | v1.0: June 2026

📊 Progress Tracking

For detailed timeline, phases, and sprint breakdown, see private workspace docs:

MASTER-RELEASE-TIMELINE.md — Complete project timeline
TIMELINE-VISUAL.md — Visual timeline Dec 2025 → June 2026
WORK-LOG.md — Session history (42+ sessions documented)