timmy-config/README.md

# timmy-config

Timmy's sovereign configuration. Everything that makes Timmy _Timmy_ — soul, memories, skins, playbooks, operational scripts, and config.

This repo is the canonical source of truth for Timmy's identity and operational state. Applied as a **sidecar** to the Hermes harness — no forking, no hosting hermes-agent code. Pull upstream updates to hermes-agent, overlay timmy-config on top.

## Structure

```
timmy-config/
├── deploy.sh                  ← Deploys config as overlay onto ~/.hermes/
├── SOUL.md                    ← Inscription 1 — the immutable conscience
├── FALSEWORK.md               ← API cost management strategy
├── config.yaml                ← Hermes harness configuration
├── channel_directory.json     ← Platform channel mappings
├── bin/                       ← Operational scripts
│   ├── claude-loop.sh         ← Parallel Claude Code agent dispatch
│   ├── gemini-loop.sh         ← Parallel Gemini Code agent dispatch
│   ├── timmy-orchestrator.sh  ← PR review, triage, merge orchestration
│   ├── workforce-manager.py   ← Agent assignment and scoring
│   ├── agent-dispatch.sh      ← Single-issue agent launcher
│   ├── agent-loop.sh          ← Generic agent loop template
│   ├── nexus-merge-bot.sh     ← Auto-merge passing PRs
│   ├── claudemax-watchdog.sh  ← Claude quota monitoring
│   ├── hermes-startup.sh      ← Boot sequence
│   ├── ops-panel.sh           ← Operational dashboard
│   ├── ops-helpers.sh         ← Shared shell functions
│   ├── ops-gitea.sh           ← Gitea API helpers
│   ├── timmy-status.sh        ← Git + Gitea status display
│   ├── timmy-loopstat.sh      ← Queue and perf stats
│   └── hotspot-keepalive.sh   ← Network keepalive
├── memories/
│   ├── MEMORY.md              ← Persistent agent memory
│   └── USER.md                ← User profile (Alexander)
├── skins/
│   ├── timmy.yaml             ← Timmy personality skin
│   └── trismegistus.yaml      ← Trismegistus personality skin
├── playbooks/
│   ├── bug-fixer.yaml         ← Test-first bug fixing
│   ├── refactor-specialist.yaml
│   ├── test-writer.yaml
│   ├── security-auditor.yaml
│   ├── issue-triager.yaml
│   └── pr-reviewer.yaml
├── cron/
│   └── jobs.json              ← Scheduled job definitions
└── docs/
    └── design-log/            ← Historical design decisions
```

## Deployment

```bash
# One command deploys everything
./deploy.sh

# Deploy and restart all agent loops
./deploy.sh --restart-loops
```

This overlays timmy-config onto `~/.hermes/` and `~/.timmy/`:
- `SOUL.md` → `~/.timmy/`
- `config.yaml` → `~/.hermes/`
- `bin/*` → `~/.hermes/bin/`
- `skins/*` → `~/.hermes/skins/`
- `memories/*` → `~/.hermes/memories/`
- `playbooks/*` → `~/.hermes/playbooks/`

## Architecture: Sidecar, Not Fork

```
hermes-agent (upstream)     timmy-config (this repo)
┌─────────────────────┐     ┌──────────────────────┐
│  Engine              │     │  Driver's seat        │
│  Tools, routing,     │     │  SOUL, memories,      │
│  agent loop, gateway │     │  skins, scripts,      │
│                      │     │  config, playbooks    │
└─────────┬───────────┘     └──────────┬───────────┘
          │                            │
          └────────────┬───────────────┘
                       ▼
                  ~/.hermes/  (merged at deploy time)
```

Never modify hermes-agent. Pull updates like any upstream dependency. Everything custom lives here.

## Origin

Migrated from `hermes/hermes-config` (archived).
Owned by Timmy_Foundation. Sovereignty and service always.