nixpkgs/README.md

# m3ta-nixpkgs

Personal Nix flake repository: custom packages, overlays, NixOS modules, and Home Manager modules.

## Features

- 🎁 **Custom Packages**: Collection of personal Nix packages
- 🔄 **Overlays**: Package modifications and enhancements
- 🐚 **Development Shells**: Pre-configured environments (Python, DevOps)
- ⚙️ **NixOS Modules**: System-level configuration modules
- 🏠 **Home Manager Modules**: User-level configuration modules
- 📚 **Library Functions**: Helper utilities for configuration management
- ❄️ **Flakes Only**: Modern Nix flakes support (no channels)

## Quick Links

- 📖 [Full Documentation](./docs)
- 🚀 [Quick Start Guide](./docs/QUICKSTART.md)
- 📚 [Architecture](./docs/ARCHITECTURE.md)
- 🤝 [Contributing](./docs/CONTRIBUTING.md)
- 📦 [Packages](./docs/packages/)
- ⚙️ [Modules](./docs/modules/)
- 📖 [Guides](./docs/guides/)

## Quick Start

```bash
# Add to your flake
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";

# Build a package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Run a package
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
```

## Available Packages

| Package            | Description                           |
| ------------------ | ------------------------------------- |
| `beads`            | Lightweight memory system for AI coding agents with graph-based issue tracking |
| `code2prompt`      | Convert code to prompts               |
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
| `launch-webapp`    | Launch web applications               |
| `mem0`             | AI memory assistant with vector storage |
| `msty-studio`      | Msty Studio application               |
| `n8n`              | Free and source-available fair-code licensed workflow automation tool |
| `opencode`         | AI coding agent built for the terminal |
| `pomodoro-timer`   | Pomodoro timer utility                |
| `rofi-project-opener` | Rofi-based project launcher        |
| `stt-ptt`          | Push to Talk Speech to Text           |
| `tuxedo-backlight` | Backlight control for Tuxedo laptops  |
| `zellij-ps`        | Project switcher for Zellij           |

## Automated Package Updates

This repository uses Gitea Actions to automatically update packages using `nix-update`:

**Workflow**: [`.gitea/workflows/nix-update.yml`](./.gitea/workflows/nix-update.yml)

**Schedule**: Runs weekly on Sundays, and can be triggered manually.

**What it does**:
- Checks all packages in `pkgs/` for updates
- Updates versions and hashes using `nix-update --flake --commit`
- Creates a new branch with updates
- Opens a pull request automatically

**Manual Trigger**:
Go to **Actions → Update Nix Packages with nix-update → Run workflow** in Gitea UI, then optionally specify a specific package to update.

**Setup Required**:
1. Create a Personal Access Token in Gitea (Settings → Applications → Generate Token)
2. Token scopes needed: `user`, `repo`, `write:issue`
3. Add token as secret: Settings → Secrets → New → `NIX_UPDATE_TOKEN`

**Note:** The `opencode-desktop` package is currently disabled due to an upstream issue with missing specta dependency hashes. See [issue #11755](https://github.com/anomalyco/opencode/issues/11755) for details. This is a temporary workaround until the upstream issue is resolved.

For detailed usage, module documentation, package references, and contribution guidelines, see the [full documentation](./docs).

## License

Individual packages may have their own licenses. Check each package's `meta.license` attribute.

## Maintainer

[@m3tam3re](https://m3ta.dev)