Clawde - Agentes Claude persistentes em Home Manager
Castrozan/clawde
Agentes Claude declarativos e persistentes como módulo Nix
Ver no GitHubFramework para declarar e gerenciar agentes Claude Code de longa duração como módulo do Home Manager (NixOS). Suporta múltiplos agentes com personalidades, cronogramas automáticos (cron heartbeat), adaptadores de canal (Discord) e comunicação peer-to-peer, orquestrando tudo via tmux e Nix.
Instalação
npx convez-ai Castrozan/clawde1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar fluxos de trabalho recorrentes com agentes Claude em produção
- Gerenciar múltiplos agentes com diferentes personalidades e permissões em uma frota
- Integrar agentes Claude em infraestrutura NixOS/Home Manager existente
Veredito

Solução niche mas sofisticada para quem usa NixOS e precisa de agentes Claude persistentes em produção. Requer expertise em Nix e arquitetura de sistemas; não é para iniciantes, mas oferece controle declarativo raro nesse espaço.
README
A tradução para o português deste README ainda está na fila.
clawde
Declarative, persistent Claude Code agents as a home-manager module.
clawde supervises long-lived Claude Code sessions as tmux windows, each driven by an optional cron heartbeat, exposed over channel adapters (Discord) and peer adapters (A2A), with per-agent personality, model, permission mode, skill directories, and agent-type defaults. A single service reconciles every declared agent on the host.
Usage
Add the flake as an input and import its home-manager module:
{
inputs.clawde.url = "github:castrozan/clawde";
inputs.clawde.inputs.nixpkgs.follows = "nixpkgs";
}
{ inputs, ... }:
{
imports = [ inputs.clawde.homeManagerModules.default ];
clawde.claudePackage = pkgs.claude-code;
clawde.agents.my-agent = {
type = "generic";
personality = "You are my-agent.";
};
}
Keep inputs.clawde.inputs.nixpkgs.follows = "nixpkgs" set: clawde's input set is
deliberately nixpkgs-only, so following your nixpkgs keeps the downstream lock free of
clawde-specific entries.
The consuming configuration injects the host-specific wiring the module does not own:
clawde.claudePackage- the claude-code package agents launch.clawde.machinesRegistry- fleet topology keyed by host alias (platform and, for the steward, tailscaleIp/username), used to buildfleet.jsonandhost-identity.json.clawde.dotfilesRepoPath- the checkout this fleet member tracks (defaults to ~/.dotfiles).clawde.stewardLiveCheckoutPayloadPath- optional live editable steward payload path; null symlinks the immutable in-store payload.healthCheckLib(module arg) - optional; when present, clawde contributes health probes.
Outputs
homeManagerModules.default/homeManagerModules.clawde- the module.stewardPayloadPath- path to the steward agent-type payload, for steward declarations.injectAgentIdentity- helper that interpolates fleet identity into an agent personality.checks.<system>.unit-tests- the agent-wrapper, heartbeat, service, steward, and a2a-server python unit suites.
Repo layout
flake.nix plain flake: inputs.nixpkgs only; exports the module, helpers, and checks
flake.lock
README.md
.gitignore
module/
default.nix imports every options/, config/, and adapter module
options/ module interface: option declarations and type contracts
interfaces.nix
agent-type-interfaces.nix
host-wiring-interfaces.nix
options.nix
lib/ pure nix helpers (no config): identity injection, window specs, paths
inject-agent-identity.nix
agent-window-spec.nix
runtime-locations.nix
runtime-paths.nix
lib.nix
config/ the config side of the module: what the options resolve into
activations.nix
agent-assertions.nix
fleet.nix
health.nix
host-identity.nix
instruction-files.nix
launch-config-files.nix
service.nix
workspace-files.nix
agent-types/ per-type defaults (generic, project-manager, steward + its payload)
channel-adapters/ user-facing channels (discord)
peer-adapters/ agent-to-agent transport (a2a server)
instructions/ runtime instruction markdown injected into agents
scripts/ python/bash runtime: agent-wrapper, heartbeat, clawde-service
tests/ pytest suites mirroring the runtime scripts
snippets/ reusable instruction fragments
The options/ -> lib/ -> config/ split is the spine: options/ declares the interface,
lib/ holds pure helpers with no config dependency, and config/ is the only side that reads
options and produces home-manager config, files, and the reconcile service.
Development
The flake provides a dev shell with every toolchain the repo uses (python312 + pytest, nix formatting and linting, shfmt, shellcheck):
nix develop
Format the whole tree (nix via nixfmt, python via ruff, shell via shfmt):
nix fmt
Run the full gate - evaluates the flake and runs the unit suites on the current system:
nix flake check
Run pytest directly while iterating (faster than a full nix flake check; needs tmux on
PATH and a writable HOME, both provided by nix develop):
python -m pytest -q \
module/scripts/tests/unit \
module/agent-types/steward/payload/tests/unit \
module/peer-adapters/a2a/a2a_server/tests
Narrow to one suite or one file the same way, for example:
python -m pytest -q module/scripts/tests/unit/test_wrapper.py
Conventions
These are enforced by review, not just tooling:
- Zero comments in any language - no inline comments, docstrings, banners, or TODO notes.
Names carry the meaning: long, descriptive, unabbreviated identifiers. A
shellcheckdirective is a functional pragma, not a comment, and is allowed. - Python 3.12 is the default for scripts. Bash is only for thin glue over shell-native tools.
- Single responsibility per function and per file.
- Test-first when fixing a bug: write the failing test, then fix.
- Never present code that has not been built and tested. For nix, a successful eval/build is the verification.
- Nix is formatted with nixfmt and linted with statix + deadnix; python is formatted and linted with ruff; bash is formatted with shfmt and linted with shellcheck.
See AGENTS.md for the full machine-readable form of these rules.
Testing
The checks.<system>.unit-tests derivation is a runCommand that runs pytest over a copy of
the source with tmux on PATH and HOME / TMUX_TMPDIR pointed at fresh temp dirs. It
covers three suites totalling 181 tests:
module/scripts/tests/unit- the agent runtime. The agent-wrapper (launch, stuck-indicator detection, pane responsiveness, session watchdog, restart scheduling, redeploy signals, resume nudge), the heartbeat (cron scheduling, tmux driver, change-gate edge triggering), the clawde-service reconcile (window-name and agent-identity reconciliation), clawde-redeploy, and the Discord reply stop hook.module/agent-types/steward/payload/tests/unit- the steward agent payload. Repository, submodule, and CI status probes, health summary, the heartbeat probe, and the activate/status/msg entry points.module/peer-adapters/a2a/a2a_server/tests- the A2A peer server. Agent card, task store, active-task coordinator watchdog, and the tmux backend (observe, send-input, meaningful-line extraction), plus the server and subprocess-backend integration tests.
Tests mock subprocess interactions; the ones that exercise tmux need a real tmux binary and a
writable HOME, which nix develop and the check derivation both supply.
The suites run across all supported systems via forAllSystems:
x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin.
CI
CI runs the same gate a developer runs locally, so a green local nix flake check predicts a
green pipeline:
nix flake check- evaluates the flake and runschecks.<system>.unit-tests(the 181-test suite) on the CI runner's system.nix fmt -- --check(or the equivalent per-tool checks) - fails the build on any file that is not formatted by nixfmt / ruff / shfmt.- statix + deadnix over the nix tree, ruff over python, shellcheck over bash - lint gates that match the conventions above.
CI is the only authority on green; the repo is kept synced and pushed only after the gate passes.