Grace Forge Labs
← Projects

SACK — Shared Agent Collaboration Kit

In progress

Composable configuration layers, multi-model agent dispatch, and runtime policy enforcement for Claude Code.

v0.2.0 | MIT License | 112K tarball

Why SACK Exists

Claude Code projects need permissions, hooks, commands, and agent workflows — but configuring them from scratch for every project is tedious, error-prone, and hard to keep consistent. SACK gives you composable layers that you mix and match per project, an installer that merges them into a single config, and runtime hooks that enforce your policies automatically. The result: a consistent, auditable, extensible Claude Code setup across all your projects.

What You Get Beyond Built-in Claude Code

  • Composable permission layers — 11 core layers that merge cleanly. Mix base, language-specific, and policy layers per project. No hand-editing settings.json.
  • Multi-model agent dispatch — Route tasks to Codex CLI, Gemini CLI, or LM Studio from a unified /gf-agent interface. Council executor runs the same task across vendors and synthesizes consensus.
  • Model routing enforcement — PreToolUse hook enforces architectural boundaries at runtime. Opus plans, Sonnet implements, specialists review. Not just convention — enforced.
  • Format-on-save (PostToolUse) — Fills a gap unique to CLI-based AI coding: IDE formatters never fire because Claude writes directly to the filesystem. This hook formats code the instant it is written. Supports ruff, biome, black, prettier, shfmt, gofmt, rustfmt.
  • Structured project workflows — /gf-init scans projects and generates token-conscious CLAUDE.md (<2000 tokens). /gf-plan spawns Opus with guardrails and schema-validated output to disk.
  • Session continuity — /gf-handoff captures session outcomes. /gf-status recovers context from cached state. /gf-cli-status shows usage across all active CLI tools.
  • Example ecosystem — Optional Notion MCP, Placid MCP, Remotion video, and macOS notification integrations in examples/ directory.

Architecture

Layers define permissions. Hooks enforce policy. Commands dispatch work. Agents execute with model routing. Examples extend all four.

Settings Layers (11 core + 4 example)
  base, python, node, ml-tools, data-tools, deployment, multi-agent, gsd, superpowers
  hooks-format, hooks-guard
        |
        v
  Merged settings.json (per project)
        |
        v
  Runtime Hooks
  ├── PreToolUse:  model-routing-guard.sh (blocks Opus from coding)
  ├── PreToolUse:  commit-guard.sh (secret detection, branch protection)
  └── PostToolUse: format-on-save.sh (ruff/biome/black/prettier/gofmt/rustfmt)
        |
        v
  Commands (18 core + 3 example)
  ├── /gf-agent, /gf-council, /gf-review, /gf-analyze...
  ├── /gf-init, /gf-plan, /gf-status, /gf-handoff...
  └── /gf-skill-gen
        |
        v
  Agent Dispatch
  ├── gf-keeper (Codex CLI)    → code review
  ├── gf-scout  (Gemini CLI)   → large-context analysis
  ├── gf-homegrown (LM Studio) → offline local inference
  └── gf-image  (Codex CLI)    → screenshot analysis

Quick Start

# Install with a preset
./install.sh ~/Code/my-project --preset ml-full

# Or pick individual layers
./install.sh ~/Code/my-project base python hooks-guard hooks-format

# See what is available
./install.sh --list-presets
./install.sh --list-layers

Requirements: bash 4.0+, python3, jq (optional, for status line)

What Gets Installed

your-project/
├── .claude/
│   ├── settings.json          # Merged from selected layers (copied)
│   ├── commands/              # 18 core slash commands (symlinked)
│   ├── hooks/                 # Policy hooks (symlinked)
│   ├── agents/                # Agent roles + task templates (symlinked)
│   ├── scripts/               # Utilities (symlinked)
│   ├── skills/                # MCP skill scaffolds (symlinked)
│   └── routing/               # Model routing config
├── CLAUDE.md                  # Project instructions (copied)
└── .gflsack.json              # Install metadata

Symlinked resources auto-update when you pull new versions. Copied files (settings.json, CLAUDE.md) are yours to customize.

Presets (9 built-in)

Presets are pre-defined layer combinations. Use ./install.sh --list-presets to see all available.

  • minimal — Base + commit guard
  • python-simple — Python + formatting + guard
  • ml-full — Full ML stack with all hooks
  • web-full — Node + deployment + all hooks
  • data-analysis — Python + database tools + multi-agent
  • data-gsd — Data analysis with GSD workflow
  • full-stack — Everything under sack governance
  • video-full — Remotion video rendering (uses example layers)
  • notion-workspace — Notion MCP integration (uses example layers)

Layers

Core Layers (11)

  • base — Git, file ops, basic shell — foundation for all projects
  • python — Python, pip, pytest, jupyter, virtual environments
  • node — npm, yarn, pnpm, node execution
  • ml-tools — MLflow, HuggingFace CLI, TensorBoard
  • data-tools — SQLite, PostgreSQL, CSV tools
  • deployment — Docker, Streamlit, GitHub CLI
  • multi-agent — Codex, Gemini, LM Studio CLI access for agent dispatch
  • gsd — GSD workflow permissions (direct git + write)
  • superpowers — Broad test/build permissions (pytest, npm test, cargo, go)
  • hooks-format — PostToolUse: auto-format on every Write/Edit
  • hooks-guard — PreToolUse: model routing guard + commit guard

Example Layers (4)

These live in examples/settings/ and are resolved automatically by the installer.

  • notion — Notion MCP tool permissions
  • placid — Placid MCP creative generation permissions
  • remotion — Remotion video rendering permissions
  • hooks-notify — macOS task completion notifications

Commands

Multi-Agent Orchestration (12)

  • /gf-agent — Unified agent dispatch with role-based delegation
  • /gf-pipeline — Sequential task chaining
  • /gf-analyze — Gemini large-context analysis
  • /gf-extract — Gemini metric/data extraction
  • /gf-map — Gemini notebook cell mapping
  • /gf-review — Codex code review
  • /gf-screenshot — Codex image analysis
  • /gf-local — Local LM Studio dispatch
  • /gf-council — Multi-model consensus
  • /gf-review-cycle — Automated review-fix-iterate loop
  • /gf-cleanup — Agent artifact cleanup
  • /gf-cli-status — CLI tool availability and usage

Project Management (5)

  • /gf-init — Scan project and generate token-conscious CLAUDE.md
  • /gf-plan — Opus architectural planning with guardrails
  • /gf-status — Quick project status from cached state
  • /gf-handoff — Session continuity summary
  • /gf-preset — Custom preset management

Skill Generator (1)

  • /gf-skill-gen — Auto-generate MCP skill scaffolds from any MCP server

Example Commands (3)

Available when example layers are installed:

  • /gf-notion — Token-efficient Notion MCP dispatcher
  • /gf-placid — Placid MCP creative asset generation
  • /gf-video — Data-driven Remotion video generation

Model Routing

SACK enforces model separation at runtime via the routing guard hook:

  • Opus — Architect. Plans, designs, orchestrates. Does not write code or read files directly.
  • Sonnet — Implementer. All code writing, edits, tests, MCP operations.
  • Haiku — Explorer. Quick file reads, codebase search, small lookups.
  • Codex (gf-keeper) — Code review via agent dispatcher.
  • Gemini (gf-scout) — Large-context analysis via agent dispatcher.
  • LM Studio (gf-homegrown) — Offline local inference.

Override with GFLS_ALLOW_OPUS_EXEC=1 for explicit escalation sessions.

Install Options

# Individual layers
./install.sh ~/project base python hooks-guard

# Preset
./install.sh ~/project --preset ml-full

# Force overwrite (re-install / update)
./install.sh ~/project --preset ml-full --force

# Skip prerequisite checks
GFLS_SKIP_PREREQS=1 ./install.sh ~/project --preset ml-full

# Copy mode (for standalone / CI environments)
./install.sh ~/project --preset ml-full --copy

# Commands or settings only
./install.sh ~/project --commands-only
./install.sh ~/project --settings-only

# Discovery
./install.sh --list-layers
./install.sh --list-presets

Companion Framework Integration

SACK coexists with companion frameworks like GSD (Get Shit Done) and Superpowers. Shared directories (commands, hooks, agents, skills) use child-level symlinks, so both frameworks write alongside each other without collision.

# Install sack with GSD layer
./install.sh ~/project --preset data-gsd

# Then install GSD alongside
npx get-shit-done-cc@latest --claude --local

# Or full stack with both companions
./install.sh ~/project --preset full-stack
npx get-shit-done-cc@latest --claude --local

The layer is the integration contract. Including gsd or superpowers in your layer selection wires their permissions and hooks into settings.json. Sack's merged settings.json is always the source of truth.

Contributing

All changes must use a feature branch with a git worktree:

git worktree add ../<project>-<feature> -b feature/<name> develop
# Work from the worktree directory
# After merge: git worktree remove ../<project>-<feature>
  • Only exception: trivial single-commit fixes directly on develop
  • Never commit directly to main
  • Shell scripts: bash 4.0+, set -euo pipefail
  • Python: python3, stdlib only
  • Hooks must exit 0 on misconfiguration (non-blocking)
  • Health check: bash -n hooks/*.sh agents/lib/*.sh

Release

v0.2.0 — 2026-03-25

  • Restructured for open source: examples/ split for optional features
  • MIT license
  • Modernized format-on-save: ruff, biome, gofmt, rustfmt with fallback chains
  • Installer resolves layers from settings/ and examples/settings/
  • Hardened installer with set -euo pipefail
  • 9 presets, 11 core layers, 18 core commands
  • Tarball: 112K, 124 files

Repository available upon request.

License

MIT License. See LICENSE file in the repository.