kawaiipunk/nixos-clanker-vm
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
nixos-clanker-vm/AGENTS.md
T
kawaiipunk 5eb121d5e6 Further changes
2026-10-09 00:07:16 +01:00

6.3 KiB
Raw Permalink Blame History

AGENTS.md

Context for AI coding agents (opencode) working in this repository.

What this is

Declarative Nix + Home Manager configuration for debian-13-opencode, a Debian 13 (trixie) non-NixOS VM running standalone Nix. This repo is the single source of truth for the user's shell, tools, and dotfiles. System-wide Nix settings are applied separately by install.sh.

There is no NixOS module system here — Home Manager is used in standalone mode.

Environment

  • OS: Debian GNU/Linux 13 (trixie), x86_64-linux, kernel 6.12.
  • Nix 2.26.3 with nix-command + flakes (declared in config/nix.conf).
  • Home Manager 26.11-pre; home.stateVersion = "26.05".
  • User user, home directory /home/user.
  • Login shell is bash, which immediately exec fish for interactive sessions.
  • Managed packages: opencode, ncdu, nano, tinfoil-proxy.
  • Managed programs: bash, fish, tmux, starship, home-manager.
  • No linter, formatter, CI, or git hooks are configured. Do not assume nixfmt, alejandra, statix, deadnix, shellcheck, or treefmt exist.
  • Working tree is expected to report warning: Git tree '...' is dirty; this is normal and does not affect evaluation.

Layout

Path Purpose
flake.nix Root flake: overlay for tinfoil-proxy, homeConfigurations.user.
home/default.nix Home Manager config: packages, file links, programs, user service.
config/nix.conf Source of truth for Nix settings (sandbox, flakes).
config/starship.toml Starship "nerd-font-symbols" preset.
config/opencode.jsonc Global opencode config, incl. the tinfoil provider.
tinfoil-proxy/flake.nix Self-contained flake exposing the tinfoil-proxy package.
tinfoil-proxy/package.nix Derivation: version, hashes, buildGoModule with go_1_27.
install.sh Installs config/nix.conf to /etc/nix/nix.conf (sudo, backs up).
flake.lock Pinned inputs; intentionally tracked for reproducibility.

Commands

home-manager switch --flake .#user      # apply the user config (the main loop)
sudo ./install.sh                       # install /etc/nix/nix.conf (idempotent)
nix build ./tinfoil-proxy               # build only the Go proxy package
nix flake show                          # list flake outputs
nix flake update                        # bump pinned inputs
nix flake update && home-manager switch --flake .#user   # update + apply

Inspect without building:

nix eval .#packages.x86_64-linux.default.pname

Inputs (currently pinned)

  • nixpkgs — nixpkgs-unstable, rev 39ad350a….
  • home-manager — rev dfadbe5…, follows this nixpkgs.
  • tinfoil-proxy — path:./tinfoil-proxy (local sub-flake).

How configuration is managed

Home Manager drives everything from home/default.nix via three mechanisms:

  1. Files linked from this repo — home.file.…source = ../config/<file>. Editing a file in config/ and re-applying updates the symlink target in ~/.config. Currently linked: starship.toml, nix/nix.conf, opencode/opencode.jsonc.
  2. Program modules — programs.<name>. Prefer these over raw dotfiles.
  3. Environment variables — home.sessionVariables.

The tinfoil-proxy user service is declared at systemd.user.services.tinfoil-proxy and starts at login/boot (linger is enabled).

Conventions

  • Declarative first. Add tools to home.packages; link config via home.file; use programs.<name> rather than hand-editing files in $HOME.
  • Use 2-space indentation in Nix, keep trailing newlines, and match the existing concise style. Do not add comments unless they add real value.
  • When renaming/moving config, keep the config/ filename, the home.file target path, and the README in sync.
  • Keep "$schema": "https://opencode.ai/config.json" at the top of config/opencode.jsonc.
  • Username and system are hardcoded in both flake.nix and tinfoil-proxy/flake.nix; keep them consistent when either changes.

Guardrails

  • Do not run home-manager switch, sudo ./install.sh, or git commit unless explicitly asked. Propose the command instead.
  • Never commit secrets. TINFOIL_API_KEY is injected via {env:...}; keep it out of the repo and the Nix store.
  • Do not remove flake.lock from tracking or add build outputs (result*) to git (already ignored by .gitignore).
  • Do not introduce a formatter/linter/CI unless asked.

Gotchas

  • packages.default in the root flake is tinfoil-proxy, not the config.
  • An overlay injects tinfoil-proxy into pkgs, which is how home/default.nix refers to pkgs.tinfoil-proxy.
  • Interactive bash exec fish, so fish (not bash) reads most interactive config; home.sessionVariables exports NIX_SHELL_PRESERVE_PROMPT=true.
  • install.sh only compares/installs config/nix.conf; it backs up any differing /etc/nix/nix.conf to /etc/nix/nix.conf.bak.<timestamp>.

OpenCode

  • config/opencode.jsonc declares the tinfoil provider via @ai-sdk/openai-compatible, pointing at the local proxy http://127.0.0.1:3301/v1, with apiKey: {env:TINFOIL_API_KEY}.
  • Model IDs and context/output limits are listed under provider.tinfoil.models. Update that block to change available models.
  • ~/.config/opencode/package.json, package-lock.json, and node_modules/ are local and unmanaged (gitignored) — Home Manager only owns opencode.jsonc.
  • opencode reads config once at startup; restart opencode after changing any config, agent, or skill file.
  • This AGENTS.md is auto-loaded as project context.

Git

  • Default branch: main. No remote is configured.
  • Commit style: short, imperative, capitalized subject (e.g. Adopt Home Manager; manage starship, nix.conf, and opencode config).
  • Only commit when explicitly asked.

Reference

README.md is the user-facing guide (setup, customization, maintenance). Keep it accurate when changing structure or commands.

Reference in New Issue View Git Blame Copy Permalink