42d94876d8
- Update AGENTS.md header with current commit (366af12) and date (2026-01-13) - Add beads, n8n, opencode to README.md Available Packages table - Update docs/README.md packages list - Create docs/packages/beads.md (220 lines) - Create docs/packages/n8n.md (310 lines) - Create docs/packages/opencode.md (346 lines) Documentation now reflects commitbc75505which added these three packages.
154 lines
5.1 KiB
Markdown
154 lines
5.1 KiB
Markdown
# m3ta-nixpkgs Documentation
|
|
|
|
Complete documentation for m3ta's personal Nix flake repository.
|
|
|
|
## Overview
|
|
|
|
m3ta-nixpkgs is a collection of custom packages, overlays, NixOS modules, and Home Manager modules organized as a modern Nix flake. This repository follows a flakes-only approach (no channels) and provides reusable components for personal infrastructure.
|
|
|
|
## Getting Started
|
|
|
|
- **[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes
|
|
- **[Architecture](./ARCHITECTURE.md)** - Understanding the repository structure and design
|
|
- **[Contributing](./CONTRIBUTING.md)** - How to contribute to this repository
|
|
|
|
## Documentation Sections
|
|
|
|
### 📚 Guides
|
|
|
|
Step-by-step guides for common tasks:
|
|
|
|
- [Getting Started](./guides/getting-started.md) - Initial setup and basic usage
|
|
- [Adding Packages](./guides/adding-packages.md) - How to add new packages
|
|
- [Port Management](./guides/port-management.md) - Managing service ports across hosts
|
|
- [Using Modules](./guides/using-modules.md) - Using NixOS and Home Manager modules
|
|
- [Development Workflow](./guides/development-workflow.md) - Development and testing workflow
|
|
|
|
### 📦 Packages
|
|
|
|
Documentation for all custom packages:
|
|
|
|
- [beads](./packages/beads.md) - Lightweight memory system for AI coding agents with graph-based issue tracking
|
|
- [code2prompt](./packages/code2prompt.md) - Convert code to prompts
|
|
- [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper
|
|
- [launch-webapp](./packages/launch-webapp.md) - Launch web applications
|
|
- [mem0](./packages/mem0.md) - AI memory assistant with vector storage
|
|
- [msty-studio](./packages/msty-studio.md) - Msty Studio application
|
|
- [n8n](./packages/n8n.md) - Free and source-available fair-code licensed workflow automation tool
|
|
- [opencode](./packages/opencode.md) - AI coding agent built for terminal
|
|
- [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility
|
|
- [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args
|
|
- [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
|
|
- [tuxedo-backlight](./packages/tuxedo-backlight.md) - Backlight control for Tuxedo laptops
|
|
- [zellij-ps](./packages/zellij-ps.md) - Project switcher for Zellij
|
|
|
|
### ⚙️ Modules
|
|
|
|
Configuration modules for NixOS and Home Manager:
|
|
|
|
#### NixOS Modules
|
|
- [Overview](./modules/nixos/overview.md) - NixOS modules overview
|
|
- [mem0](./modules/nixos/mem0.md) - Mem0 REST API server module
|
|
- [ports](./modules/nixos/ports.md) - Port management module
|
|
|
|
#### Home Manager Modules
|
|
- [Overview](./modules/home-manager/overview.md) - Home Manager modules overview
|
|
- [CLI Tools](./modules/home-manager/cli/) - CLI-related modules
|
|
- [rofi-project-opener](./modules/home-manager/cli/rofi-project-opener.md) - Rofi-based project launcher
|
|
- [stt-ptt](./modules/home-manager/cli/stt-ptt.md) - Push to Talk Speech to Text
|
|
- [zellij-ps](./modules/home-manager/cli/zellij-ps.md) - Zellij project switcher
|
|
- [Coding](./modules/home-manager/coding/) - Development-related modules
|
|
- [editors](./modules/home-manager/coding/editors.md) - Editor configurations
|
|
|
|
### 📖 Reference
|
|
|
|
Technical references and APIs:
|
|
|
|
- [Functions](./reference/functions.md) - Library functions documentation
|
|
- [Patterns](./reference/patterns.md) - Code patterns and anti-patterns
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
m3ta-nixpkgs/
|
|
├── docs/ # This directory
|
|
│ ├── README.md
|
|
│ ├── QUICKSTART.md
|
|
│ ├── ARCHITECTURE.md
|
|
│ ├── CONTRIBUTING.md
|
|
│ ├── guides/
|
|
│ ├── packages/
|
|
│ ├── modules/
|
|
│ └── reference/
|
|
├── pkgs/ # Custom packages
|
|
├── modules/
|
|
│ ├── nixos/ # NixOS modules
|
|
│ └── home-manager/ # Home Manager modules
|
|
├── lib/ # Library functions
|
|
├── shells/ # Development shells
|
|
├── overlays/ # Package overlays
|
|
├── templates/ # Templates
|
|
└── examples/ # Usage examples
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
### Flakes-Only Approach
|
|
|
|
This repository uses modern Nix flakes exclusively. No channels or `nix-channel` commands are needed. All dependencies are declaratively specified in `flake.nix`.
|
|
|
|
### Namespace Convention
|
|
|
|
All modules use the `m3ta.*` namespace:
|
|
|
|
- `m3ta.ports.*` - Port management
|
|
- `m3ta.mem0.*` - Mem0 service configuration
|
|
- `m3ta.*.enable` - Enable/disable modules
|
|
|
|
### Port Management
|
|
|
|
Centralized port management across hosts using the `m3ta.ports` module:
|
|
|
|
```nix
|
|
m3ta.ports = {
|
|
enable = true;
|
|
definitions = { mem0 = 8000; };
|
|
hostOverrides.laptop = { mem0 = 8080; };
|
|
currentHost = "laptop";
|
|
};
|
|
```
|
|
|
|
## Supported Systems
|
|
|
|
- `x86_64-linux` - Primary
|
|
- `aarch64-linux` - ARM Linux
|
|
- `x86_64-darwin` - macOS (Intel)
|
|
- `aarch64-darwin` - macOS (Apple Silicon)
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# Validate flake
|
|
nix flake check
|
|
|
|
# Format code
|
|
nix fmt
|
|
|
|
# Build package
|
|
nix build .#<package-name>
|
|
|
|
# List outputs
|
|
nix flake show
|
|
|
|
# Enter dev shell
|
|
nix develop
|
|
```
|
|
|
|
## License
|
|
|
|
Individual packages may have their own licenses. Check each package's `meta.license` attribute.
|
|
|
|
## Maintainer
|
|
|
|
[@m3tam3re](https://m3ta.dev)
|