feat: add notesmd-cli package and flake checks

- Add notesmd-cli package for Obsidian CLI interaction - Add flake checks for package build verification - Add documentation for notesmd-cli, sidecar, and td - Update AGENTS.md to reference td instead of beads - Format pkgs/default.nix with proper braces
2026-02-14 07:15:06 +01:00
parent 56a7a7bfa8
commit e6c22a04d7
9 changed files with 462 additions and 26 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,8 +5,8 @@
 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-01-13
-**Commit:** 366af12
+**Generated:** 2026-02-14
+**Commit:** dc2f3b6
 **Branch:** master

 ## OVERVIEW
@@ -155,16 +155,16 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
 - **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.

-## Issue Tracking
+## Task Management

-This project uses **bd (beads)** for issue tracking.
-Run `bd prime` for workflow context, or install hooks (`bd hooks install`) for auto-injection.
+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:**

- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd sync` - Sync with git (run at session end)
+- `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: `bd prime`
+For full workflow details, see the [td documentation](./docs/packages/td.md).
--- a/README.md
+++ b/README.md
@@ -47,11 +47,14 @@ nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
 | `mem0`             | AI memory assistant with vector storage |
 | `msty-studio`      | Msty Studio application               |
 | `n8n`              | Free and source-available fair-code licensed workflow automation tool |
+| `notesmd-cli`      | Obsidian CLI (Community) - Interact with Obsidian in the terminal |
 | `opencode`         | AI coding agent built for the terminal |
 | `opencode-desktop` | OpenCode Desktop App with Wayland support (includes workaround for upstream issue #11755) |
 | `pomodoro-timer`   | Pomodoro timer utility                |
 | `rofi-project-opener` | Rofi-based project launcher        |
+| `sidecar`          | Companion tool for CLI agents with diffs, file trees, and task management |
 | `stt-ptt`          | Push to Talk Speech to Text           |
+| `td`               | Minimalist CLI for tracking tasks across AI coding sessions |
 | `tuxedo-backlight` | Backlight control for Tuxedo laptops  |
 | `zellij-ps`        | Project switcher for Zellij           |

--- a/docs/README.md
+++ b/docs/README.md
@@ -35,10 +35,13 @@ Documentation for all custom packages:
 - [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
+- [notesmd-cli](./packages/notesmd-cli.md) - Obsidian CLI (Community) - Interact with Obsidian in the terminal
 - [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
+- [sidecar](./packages/sidecar.md) - Companion tool for CLI agents with diffs, file trees, and task management
 - [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
+- [td](./packages/td.md) - Minimalist CLI for tracking tasks across AI coding sessions
 - [tuxedo-backlight](./packages/tuxedo-backlight.md) - Backlight control for Tuxedo laptops
 - [zellij-ps](./packages/zellij-ps.md) - Project switcher for Zellij

--- a/docs/packages/notesmd-cli.md
+++ b/docs/packages/notesmd-cli.md
@@ -0,0 +1,117 @@
+# notesmd-cli
+
+Obsidian CLI (Community) - Interact with Obsidian in the terminal.
+
+## Description
+
+notesmd-cli is a command-line interface for interacting with Obsidian, the popular knowledge management and note-taking application. It allows you to create, search, and manipulate notes directly from the terminal.
+
+## Features
+
+- 📝 **Note Creation**: Create new notes from the command line
+- 🔍 **Search**: Search through your Obsidian vault
+- 📂 **Vault Management**: Interact with your vault structure
+- 🔗 **WikiLink Support**: Work with Obsidian's WikiLink format
+- 🏷️ **Tag Support**: Manage and search by tags
+- ⚡ **Fast**: Lightweight Go binary with no external dependencies
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    notesmd-cli
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.notesmd-cli
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#notesmd-cli
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Show help
+notesmd-cli --help
+
+# Create a new note
+notesmd-cli new "My Note Title"
+
+# Search notes
+notesmd-cli search "search term"
+
+# List notes
+notesmd-cli list
+```
+
+### Working with Vaults
+
+```bash
+# Specify vault path
+notesmd-cli --vault /path/to/vault new "Note Title"
+
+# Open a note in Obsidian
+notesmd-cli open "Note Name"
+```
+
+### Advanced Usage
+
+```bash
+# Search with tags
+notesmd-cli search --tag "project"
+
+# Append to existing note
+notesmd-cli append "Note Name" "Additional content"
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OBSIDIAN_VAULT`: Default vault path
+
+### Command Line Options
+
+Run `notesmd-cli --help` for a complete list of options.
+
+## Build Information
+
+- **Version**: 0.3.0
+- **Language**: Go
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/Yakitrak/notesmd-cli)
+- **Vendor Hash**: null (no external dependencies)
+
+## Platform Support
+
+- Linux
+- macOS (Unix systems)
+
+## Notes
+
+- No vendor dependencies (pure Go stdlib)
+- The binary is named `notesmd-cli` (not `notesmd`)
+- This is the community CLI, not the official Obsidian CLI
+
+## Related
+
+- [Obsidian](https://obsidian.md) - The Obsidian application
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
--- a/docs/packages/sidecar.md
+++ b/docs/packages/sidecar.md
@@ -0,0 +1,134 @@
+# sidecar
+
+A companion tool for CLI coding agents, providing diffs, file trees, conversation history, and task management with td integration.
+
+## Description
+
+sidecar is a terminal UI tool designed to enhance the experience of using AI coding agents in the terminal. It provides a side panel interface for viewing diffs, file trees, conversation history, and integrates with `td` for task management across coding sessions.
+
+## Features
+
+- 🔀 **Diff Viewer**: Visual diff display for code changes
+- 📁 **File Tree**: Navigate and understand project structure
+- 💬 **Conversation History**: Review and search past AI interactions
+- ✅ **Task Management**: Integrated with `td` for tracking tasks
+- 🖥️ **Terminal UI**: Clean interface using tmux panes
+- 🤖 **AI Agent Integration**: Designed to work with opencode and similar CLI agents
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    sidecar
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.sidecar
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#sidecar
+```
+
+## Usage
+
+### Starting sidecar
+
+```bash
+# Start sidecar alongside your AI coding agent
+sidecar
+
+# Start with a specific agent
+sidecar --agent opencode
+```
+
+### Basic Commands
+
+```bash
+# Show help
+sidecar --help
+
+# Check version
+sidecar --version
+```
+
+## Dependencies
+
+sidecar is packaged with the following runtime dependencies:
+
+- **opencode**: AI coding agent
+- **td**: Task tracking CLI
+- **tmux**: Terminal multiplexer for UI layout
+
+These are automatically included in the PATH when running sidecar.
+
+## Workflow Integration
+
+### Typical Session
+
+1. Start `sidecar` in your project directory
+2. The tool opens a tmux session with panes for:
+   - Your AI coding agent (opencode)
+   - Task list (via td)
+   - Diff viewer
+   - File tree navigator
+3. Work with your AI agent as usual
+4. View diffs and changes in real-time
+5. Track tasks using the integrated td panel
+
+### With opencode
+
+```bash
+# sidecar automatically integrates with opencode
+cd your-project
+sidecar
+```
+
+## Configuration
+
+### Environment Variables
+
+- `SIDECAR_CONFIG`: Custom configuration file path
+- `SIDECAR_AGENT`: Default AI agent to use (default: opencode)
+
+### Customization
+
+Configuration is managed through sidecar's own config system. See the upstream documentation for details.
+
+## Build Information
+
+- **Version**: 0.71.1
+- **Language**: Go
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/marcus/sidecar)
+
+## Platform Support
+
+- Linux
+- macOS (Unix systems)
+
+## Notes
+
+- Tests are disabled in the Nix package build
+- The package wraps the binary with required dependencies (opencode, td, tmux) in PATH
+- Version check is enabled for the Nix package
+
+## Related
+
+- [td](./td.md) - Task tracking CLI used by sidecar
+- [opencode](./opencode.md) - AI coding agent integration
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
--- a/docs/packages/td.md
+++ b/docs/packages/td.md
@@ -0,0 +1,130 @@
+# td
+
+Minimalist CLI for tracking tasks across AI coding sessions.
+
+## Description
+
+td (task daemon) is a lightweight command-line tool designed for tracking tasks during AI-assisted coding sessions. It provides a simple, fast way to manage todos and maintain context across conversations with AI coding agents.
+
+## Features
+
+- ✅ **Minimal Task Tracking**: Simple, focused task management
+- 🤖 **AI Session Aware**: Designed to work with AI coding workflows
+- 📊 **Usage Tracking**: Track session usage and context
+- 🔄 **Session Continuity**: Resume tasks from previous sessions
+- 📝 **Git Integration**: Works alongside git workflows
+- ⚡ **Fast**: Lightweight Go binary with minimal overhead
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    td
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.td
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#td
+```
+
+## Usage
+
+### Starting a Session
+
+```bash
+# Start a new session and view current tasks
+td usage --new-session
+
+# Quick view of current tasks (no session tracking)
+td usage -q
+```
+
+### Basic Commands
+
+```bash
+# Show version
+td version
+
+# View help
+td --help
+```
+
+### Task Management
+
+td integrates with AI coding workflows to track tasks across sessions. Use it at the start of conversations to establish context:
+
+```bash
+# At conversation start (or after /clear)
+td usage --new-session
+
+# For subsequent reads within the same session
+td usage -q
+```
+
+## Integration with AI Agents
+
+td is designed to be used by AI coding agents as part of their workflow:
+
+1. **Session Start**: Agent reads current tasks with `td usage --new-session`
+2. **Work Progress**: Tasks are tracked and updated during the session
+3. **Session End**: State is preserved for the next session
+
+### Example Integration
+
+In an AI agent's system prompt or configuration:
+
+```
+You must run td usage --new-session at conversation start (or after /clear) to see current work.
+Use td usage -q for subsequent reads.
+```
+
+## Configuration
+
+### Environment Variables
+
+- `TD_DATA_DIR`: Custom directory for td data storage
+
+### Data Storage
+
+Task data is stored locally in the project or user directory. See upstream documentation for exact storage location.
+
+## Build Information
+
+- **Version**: 0.34.0
+- **Language**: Go
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/marcus/td)
+
+## Platform Support
+
+- Linux
+- macOS (Unix systems)
+
+## Notes
+
+- Tests are disabled in the Nix package build due to git worktree operations
+- Version check is enabled for the Nix package (`td version`)
+- Minimal dependencies - pure Go binary
+
+## Related
+
+- [sidecar](./sidecar.md) - Uses td for integrated task management
+- [opencode](./opencode.md) - AI coding agent that integrates with td
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide
--- a/flake.nix
+++ b/flake.nix
@@ -87,6 +87,19 @@
    # Formatter for 'nix fmt'
    formatter = forAllSystems (system: (pkgsFor system).alejandra);

+    # Checks for 'nix flake check' - verifies all packages build
+    checks = forAllSystems (system: let
+      pkgs = pkgsFor system;
+      packages = import ./pkgs {inherit pkgs inputs;};
+    in
+      builtins.mapAttrs (name: pkg: pkgs.lib.hydraJob pkg) packages
+      // {
+        formatting = pkgs.runCommand "check-formatting" {} ''
+          ${pkgs.alejandra}/bin/alejandra --check ${./.}
+          touch $out
+        '';
+      });
+
    # Templates for creating new packages/modules
    templates = {
      package = {
--- a/pkgs/default.nix
+++ b/pkgs/default.nix
@@ -1,22 +1,27 @@
-{ pkgs, inputs ? null, ... }: {
+{
+  pkgs,
+  inputs ? null,
+  ...
+}: {
  # Custom packages registry
  # Each package is defined in its own directory under pkgs/
-  beads = pkgs.callPackage ./beads { };
-  sidecar = pkgs.callPackage ./sidecar { };
-  td = pkgs.callPackage ./td { };
-  code2prompt = pkgs.callPackage ./code2prompt { };
-  hyprpaper-random = pkgs.callPackage ./hyprpaper-random { };
-  launch-webapp = pkgs.callPackage ./launch-webapp { };
-  mem0 = pkgs.callPackage ./mem0 { };
-  msty-studio = pkgs.callPackage ./msty-studio { };
-  n8n = pkgs.callPackage ./n8n { };
-  pomodoro-timer = pkgs.callPackage ./pomodoro-timer { };
-  rofi-project-opener = pkgs.callPackage ./rofi-project-opener { };
-  stt-ptt = pkgs.callPackage ./stt-ptt { };
-  tuxedo-backlight = pkgs.callPackage ./tuxedo-backlight { };
-  zellij-ps = pkgs.callPackage ./zellij-ps { };
+  beads = pkgs.callPackage ./beads {};
+  sidecar = pkgs.callPackage ./sidecar {};
+  td = pkgs.callPackage ./td {};
+  code2prompt = pkgs.callPackage ./code2prompt {};
+  hyprpaper-random = pkgs.callPackage ./hyprpaper-random {};
+  launch-webapp = pkgs.callPackage ./launch-webapp {};
+  mem0 = pkgs.callPackage ./mem0 {};
+  msty-studio = pkgs.callPackage ./msty-studio {};
+  notesmd-cli = pkgs.callPackage ./notesmd-cli {};
+  n8n = pkgs.callPackage ./n8n {};
+  pomodoro-timer = pkgs.callPackage ./pomodoro-timer {};
+  rofi-project-opener = pkgs.callPackage ./rofi-project-opener {};
+  stt-ptt = pkgs.callPackage ./stt-ptt {};
+  tuxedo-backlight = pkgs.callPackage ./tuxedo-backlight {};
+  zellij-ps = pkgs.callPackage ./zellij-ps {};

  # Imported from flake inputs
  opencode = inputs.opencode.packages.${pkgs.system}.opencode;
-  opencode-desktop = pkgs.callPackage ./opencode-desktop { inherit inputs; };
+  opencode-desktop = pkgs.callPackage ./opencode-desktop {inherit inputs;};
 }
--- a/pkgs/notesmd-cli/default.nix
+++ b/pkgs/notesmd-cli/default.nix
@@ -0,0 +1,31 @@
+{
+  lib,
+  buildGoModule,
+  fetchFromGitHub,
+  nix-update-script,
+}:
+buildGoModule (finalAttrs: {
+  pname = "notesmd-cli";
+  version = "0.3.0";
+
+  src = fetchFromGitHub {
+    owner = "Yakitrak";
+    repo = "notesmd-cli";
+    tag = "v${finalAttrs.version}";
+    hash = "sha256-KJRaJ9Fw7oh108ljKw1Eb2r7hZXlFWC2NOrjhliuzVQ=";
+  };
+
+  vendorHash = null;
+
+  ldflags = ["-s" "-w"];
+
+  passthru.updateScript = nix-update-script {};
+
+  meta = {
+    description = "Obsidian CLI (Community) - Interact with Obsidian in the terminal";
+    homepage = "https://github.com/Yakitrak/notesmd-cli";
+    license = lib.licenses.mit;
+    platforms = lib.platforms.unix;
+    mainProgram = "notesmd-cli";
+  };
+})