NixOS/README.org

JawZ NixOS Configuration

• Overview
• MCP Server (nixos-mcp)
  • What it is
  • Tool Catalog
  • Quick Start (new users)
  • Reference
• Repository Structure
  • Docs and Guidance
  • MCP Server
  • Flake Parts
• Flake Inputs (high level)
  • Core Inputs
• Maintenance
  • Regular Tasks
  • Backup Strategy
• Contributing
  • Code Style
  • Pull Requests
• License
• Contact

Overview

This repository is a NixOS configuration flake with a local MCP server (`nixos-mcp`) that helps Codex CLI work with the repo’s documentation and maintenance workflows. The README focuses on how to use the MCP server and how the repo is structured.

MCP Server (nixos-mcp)

What it is

Local-only MCP server that exposes repo documentation helpers over stdio so Codex CLI can read the constitution, playbooks, and reference map without manual navigation.

Tool Catalog

show-constitution

Open docs/constitution.md

list-playbooks

List docs/playbooks/

show-reference

Open docs/reference/index.md

search-docs

Search the docs set

list-mcp-tasks

Show MCP tasks from specs/002-mcp-server/tasks.md

sync-docs

Check tool catalog vs. docs anchors

Quick Start (new users)

# Enter the MCP dev shell (includes codex + nixos-mcp)
nix develop .#mcp

# Run the MCP server (stdio mode)
nixos-mcp

Configure Codex CLI to use a local stdio MCP endpoint and allowlist nixos-mcp in .codex/requirements.toml. The dev shell sets CODEX_HOME.codex= for a repo-local Codex config.

Reference

Detailed invocation notes live in docs/reference/mcp-server.md.

Repository Structure

Docs and Guidance

docs/constitution.md

AI constitution (authoritative rules)

docs/reference/index.md

Reference map

docs/reference/mcp-server.md

MCP server reference

docs/playbooks/

Repeatable workflows

specs/002-mcp-server/

MCP feature plan + tasks

MCP Server

scripts/mcp-server/

Python MCP server implementation, tests, and CLI

modules/dev/mcp.nix

Dev shell and optional global install

Flake Parts

parts/core.nix

Shared library + base composition

parts/hosts.nix

Host definitions

parts/packages.nix

Package outputs

parts/devshells.nix

Dev shells (including MCP)

Flake Inputs (high level)

Core Inputs

• nixpkgs (25.11) and nixpkgs-small (25.11-small)
• nixpkgs-unstable (rolling)
• flake-parts (structure)
• home-manager (user configs)
• stylix (theming)
• sops-nix (secrets integration)
• nur, nix-gaming, hyprland (extra packages)
• Content inputs: wallpapers, fonts, qbit_manage
• Repo inputs: jawz-scripts, prem2resolve, lidarr-mb-gap
• Check service-specific documentation

Maintenance

Regular Tasks

• Update flake inputs weekly
• Review and rotate secrets quarterly
• Update system packages monthly
• Clean old generations: sudo nix-collect-garbage -d

Backup Strategy

• Configuration is version controlled
• Secrets are encrypted and backed up
• BTRFS snapshots for data protection

Contributing

Code Style

• Use consistent formatting
• Add comments for complex configurations
• Follow Nix conventions

Pull Requests

• Test changes on development host first
• Update documentation as needed
• Ensure all secrets are properly managed

License

This configuration is for personal use. Please respect the licenses of individual packages and services used.

Contact

For questions or issues, contact danilo.reyes.251@proton.me

—

Last updated: 2025