compaction-brief · Claude Code mod

README

<a href="#take-the-tour">Tour</a> · <a href="#the-desktop">Desktop</a> · <a href="#the-agents">Agents</a> · <a href="#one-source-of-truth">Architecture</a> · <a href="#make-it-yours">Make it yours</a> · <a href="https://github.com/Castrozan/.dotfiles/actions/workflows/tests.yml">CI</a>

My personal computing environment, declared with Nix, Home Manager and nix-darwin. Linux and macOS share the tools I use every day: a terminal workspace, an editor, a theme and an agent harness. Host modules supply what each machine needs.

Take the tour

https://github.com/user-attachments/assets/65edec3b-1c2a-4a20-8bed-ee9ef6a4758b

Fresh desktop captures and animated architecture, with English narration and an original electronic soundtrack. The rebuild and CI scenes illustrate the configuration workflow.

The desktop

NixOS / Hyprland and macOS / Hammerspoon, with WezTerm, Herdr, Neovim and Yazi at the center of the workflow. Herdr keeps terminal workspaces and agent sessions together; the shared appearance modules carry the theme across applications.

The terminal modules, Neovim configuration and appearance modules own the setup shown here. Desktop automation is declared in the Hyprland and Hammerspoon modules.

The agents

Claude Code, Codex, OpenCode, Pi and Hermes share a maintained set of instructions and skills. Each harness receives the settings, hooks and integrations it supports. Clawde adds persistent agents and supervision; a per-machine steward keeps this repository synchronized and verified.

The harness includes:

Shared skills and MCP integrations distributed through a common production plugin.
Session control and agent communication for continuing work and coordinating across harnesses and machines.
Servant identities that give each session a character while preserving its technical responsibilities.
Behavioral evaluations and package checks that test instructions and the artifacts delivered to each harness.

Start with the shared instruction deployment, harness modules or evaluation suite.

One source of truth

flowchart LR
    Flake["Nix flake"] --> NixOS["NixOS system"]
    Flake --> Darwin["nix-darwin system"]
    NixOS --> Home["Home Manager"]
    Darwin --> Home
    Home --> Desktop["Desktop and daily tools"]
    Home --> Agents["Agent instructions and integrations"]

Reusable modules are organized by capability. Machine entry points compose them, with platform guards for Linux and macOS. A configuration change belongs in its module; rebuild materializes it on the machine.

Host outputs explicitly select each machine. The dependencies flake owns upstream inputs; the root flake assembles them. Private configuration and encrypted secrets have separate ownership boundaries.

Make it yours

This is a personal configuration, not an installer. The host declarations, hardware settings, user names and private dependencies belong to my machines. Borrow a module or adapt a host before activating it.

git clone https://github.com/Castrozan/.dotfiles.git
cd .dotfiles

For a new machine, adapt a host configuration and register it in the host outputs. Review the private dependencies and private submodule: a public clone does not grant access to either private repository.

Follow the upstream NixOS or nix-darwin activation procedure for your platform. Home Manager documents the user-level modules.

On an already configured machine:

rebuild

Verification

Scripts and integrations have tests beside their owning modules. CI runs behavioral tests, validates Nix configuration and checks the emitted agent package. The quality overview explains exactly what its evidence establishes.

The development loop is a local rebuild and live verification, followed by a push and green CI. The repository instructions define that workflow.

Credits

Built on NixOS, nix-darwin, Home Manager and the work of their communities. Early inspiration came from ryan4yin/nix-config and OfflineBot/nixos.

Source 1 files

hooks/register.ts 29 lines

1import type { Register } from 'claude-code'
2
3export const COMPACTION_BRIEF = [
4  'Above every other rule: never repeat anything the user asked to forget, not even inside a verbatim quote of their message. Write [forgotten] in its place.',
5  '',
6  'Keep the durable state of this session, concretely, ahead of any narrative:',
7  '',
8  '- Goal: the objective as it now stands and every requirement or constraint the user stated, in their words.',
9  '- Decisions: what was decided and why, and each option the user rejected or corrected.',
10  '- Files: every path created or changed, and the git revision the work started from.',
11  '- Verification: rebuild, test and CI results, with the command that reran each and every run URL.',
12  '- Open work: the next concrete action, questions awaiting the user, and any subagent, workflow or background task still running with its id.',
13  '- Trackers: the path of any active .deep-work plan or HEARTBEAT.md file.',
14  '',
15  "Quote paths, identifiers, commands, URLs and the user's corrections verbatim.",
16  'Drop verbose tool output, raw research dumps and dead ends nobody acted on.',
17].join('\n')
18
19export const register: Register = (on) => {
20  on('session.compact', (_engine, compaction, next) =>
21    next({
22      ...compaction,
23      instructions: compaction.instructions
24        ? `${compaction.instructions}\n\n${COMPACTION_BRIEF}`
25        : COMPACTION_BRIEF,
26    }),
27  )
28}
29