nixpkgs/AGENTS.md

m3ta-nixpkgs Knowledge Base

MANDATORY: Use td for Task Management

You must run td usage --new-session at conversation start (or after /clear) to see current work. Use td usage -q for subsequent reads.

Generated: 2026-02-14 Commit: dc2f3b6 Branch: master

OVERVIEW

Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).

STRUCTURE

.
├── flake.nix              # Entry: packages, overlays, modules, shells, lib
├── pkgs/                  # Custom packages (one dir each, callPackage registry)
├── modules/
│   ├── nixos/             # System modules (ports.nix)
│   └── home-manager/      # User modules by category (cli/, coding/, ports.nix)
├── lib/                   # Shared utilities (ports.nix)
├── shells/                # Dev environments (default, python, devops)
├── overlays/mods/         # Package modifications (n8n version bump)
├── templates/             # Boilerplate for new packages/modules
├── examples/              # Usage examples
└── .gitea/workflows/     # CI/CD workflows (nix-update automation)

WHERE TO LOOK

Task	Location	Notes
Add package	pkgs/<name>/default.nix	Register in pkgs/default.nix
Add NixOS module	modules/nixos/<name>.nix	Import in modules/nixos/default.nix
Add HM module	modules/home-manager/<category>/	Category: cli, coding, or root
Override nixpkgs pkg	overlays/mods/<name>.nix	Import in overlays/mods/default.nix
Add dev shell	shells/<name>.nix	Register in shells/default.nix
Use port management	config.m3ta.ports.get "service"	Host-specific via hostOverrides
CI/CD workflows	.gitea/workflows/<name>.yml	Automated package updates (nix-update)

CONVENTIONS

Formatter: nix fmt before commit (alejandra)

Naming:

• Packages: lowercase-hyphen (e.g., hyprpaper-random)
• Variables: camelCase (e.g., portHelpers)
• Module options: m3ta.* namespace

Imports: Multi-line, trailing commas:

{
  lib,
  stdenv,
  fetchFromGitHub,
}:

Modules: Standard pattern:

{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
  };
  config = mkIf cfg.enable { ... };
}

Meta: Always include all fields:

meta = with lib; {
  description = "...";
  homepage = "...";
  license = licenses.mit;
  platforms = platforms.linux;
  mainProgram = "...";
};

PACKAGE PATTERNS

Rust: rustPlatform.buildRustPackage rec { cargoLock.lockFile = src + "/Cargo.lock"; }

Shell: writeShellScriptBin "name" ''script'' or mkDerivation with custom installPhase

AppImage: appimageTools.wrapType2 { ... }

Custom fetcher: fetchFromGitea { domain = "code.m3ta.dev"; owner = "m3tam3re"; ... }

MODULE PATTERNS

Simple: options.cli.name = { enable = mkEnableOption "..."; }; config = mkIf cfg.enable { ... };

Multiple: config = mkMerge [ (mkIf cfg.x.enable { ... }) (mkIf cfg.y.enable { ... }) ];

Shared lib: portsLib = import ../../lib/ports.nix { inherit lib; }; portHelpers = portsLib.mkPortHelpers { ... };

LIBRARY FUNCTIONS

lib.ports

Port management utilities. See Port Management.

lib.agents

Harness-agnostic agent management. Reads canonical agent.toml from the AGENTS flake input and renders tool-specific configs.

Functions:

Function	Purpose
loadCanonical { agentsInput }	Load canonical agents from AGENTS flake
renderForOpencode { pkgs, canonical, modelOverrides }	Render to OpenCode file-based agents
renderForClaudeCode { pkgs, canonical, modelOverrides }	Render to Claude Code agents + settings.json
renderForPi { pkgs, canonical }	Render to Pi AGENTS.md + SYSTEM.md
renderForTool { pkgs, agentsInput, tool, modelOverrides }	Dispatch to correct renderer
shellHookForTool { pkgs, agentsInput, tool, modelOverrides }	Generate devShell shellHook

lib.coding-rules

Coding rules injection (renamed from lib.opencode-rules). The old name still works.

Function	Purpose
mkCodingRules { agents, languages, concerns, frameworks }	Generate rules config + shellHook
mkOpencodeRules	Backward-compat alias for mkCodingRules

PORT MANAGEMENT

Central port management: config.m3ta.ports.get "service" with host-specific via hostOverrides

Generated: /etc/m3ta/ports.json (NixOS), ~/.config/m3ta/ports.json (HM)

COMMANDS

nix flake check              # Validate flake
nix fmt                      # Format (alejandra)
nix build .#<pkg>            # Build package
nix flake show               # List outputs
nix develop                  # Enter dev shell
nix develop .#python         # Python shell
nix develop .#devops         # DevOps shell

# In dev shell only:
statix check .               # Lint
deadnix .                    # Find dead code

ANTI-PATTERNS

Don't	Do Instead
lib.fakeHash in commits	Get real hash: nix build, copy from error
Flat module files	Organize by category (cli/, coding/)
Hardcode ports	Use m3ta.ports module
Skip meta fields	Include all: description, homepage, license, platforms, mainProgram
with pkgs; in modules	Explicit pkgs.package or with pkgs; [ ... ] in lists only

COMMIT FORMAT

type: brief description

Types: feat, fix, docs, style, refactor, chore

NOTES

• Hash fetching: Use lib.fakeHash initially, build to get real hash
• HM modules: Category subdirs (cli/, coding/) have own default.nix aggregators
• Ports module: Different for NixOS vs HM (HM adds generateEnvVars option)
• Overlays: modifications overlay uses {prev}: pattern, not {final, prev}:
• Dev shell tools: statix, deadnix only available inside nix develop
• Automated package updates: Packages are automatically updated weekly via Gitea Actions using nix-update. Review PRs from the automation before merging. For urgent updates, manually run the workflow or update manually.

Task Management

This project uses td for tracking tasks across AI coding sessions. Run td usage --new-session at conversation start to see current work. Use td usage -q for subsequent reads.

Quick reference:

• td usage --new-session - Start new session and view tasks
• td usage -q - Quick view of current tasks (subsequent reads)
• td version - Check version

For full workflow details, see the td documentation.

MIGRATION: Agent System (OpenCode → Canonical TOML)

The agent system was migrated from embedded agents.json to harness-agnostic canonical agent.toml + system-prompt.md in the AGENTS repo. Renderers in lib/agents.nix generate tool-specific configs.

What changed in this repo

• lib/agents.nix: New — 3 renderers (OpenCode, Claude Code, Pi) + dispatcher + shellHook
• lib/coding-rules.nix: Renamed from opencode-rules.nix, mkCodingRules replaces mkOpencodeRules
• modules/home-manager/coding/agents/: New — per-tool HM sub-modules
• modules/home-manager/coding/opencode.nix: Slimmed — no longer handles agents/skills/context
• flake.nix: Exports new agents HM module

What the user must do

See modules/home-manager/AGENTS.md for the full migration guide. Summary:

1. Move agentsInput/externalSkills from coding.opencode to coding.agents.opencode
2. Add modelOverrides with previously hardcoded model strings
3. Run home-manager switch
4. Remove legacy agents.json + prompts/*.txt from AGENTS repo
5. Remove lib.agentsJson backward-compat bridge from AGENTS flake.nix