streamd/README.md

strea.md

Strea.md is a personal knowledge management and time-tracking CLI tool. It organizes time-ordered markdown files using @tag annotations, letting you manage tasks, track time, and query your notes from the terminal.

Installation

Debian/Ubuntu (.deb package)

Download and install the latest release:

wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd_X.Y.Z_amd64.deb
sudo dpkg -i streamd_X.Y.Z_amd64.deb

This includes shell completions for bash, zsh, and fish.

Static Binary

Download the statically-linked binary:

wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd-X.Y.Z-linux-x86_64
chmod +x streamd-X.Y.Z-linux-x86_64
sudo mv streamd-X.Y.Z-linux-x86_64 /usr/local/bin/streamd

Nix

Using the flake directly:

nix run git+https://git.konstantinfickel.de/kfickel/streamd

Or add to your NixOS/Home Manager configuration using the provided homeManagerModules.default.

Core Concepts

• Shards — Sections of markdown files, organized hierarchically by headings. Each shard can contain markers, tags, and nested child shards.
• Markers — Special @tags like @Task, @Done, @Waiting, or @Timesheet that give shards semantic meaning and place them into dimensions.
• Dimensions — Classification axes (e.g. task state, project, timesheet) that categorize shards. Some dimensions propagate to child shards.

File Format

Markdown files are named with a timestamp: YYYYMMDD-HHMMSS [markers].md

For example: 20260131-210000 Task Streamd.md

An optional _file_type segment can follow the timestamp to classify the file:

YYYYMMDD-HHMMSS_<file_type> [markers].md

For example: 20260413-083000_daily.md — the daily prefix is stored as the file_type dimension and propagates to all child shards.

Within files, @-prefixed markers at the beginning of paragraphs or headings define how a shard is categorized.

Commands

• streamd / streamd new — Create a new timestamped markdown entry, opening your editor
• streamd daily [YYYYMMDD] — Open today's daily file (or create it if missing); pass a date to open that day's file instead
• streamd todo — Show all open tasks (shards with @Task markers), numbered for easy reference
• streamd todo N edit — Edit task N in your editor, jumping to the task's line
• streamd todo N done — Mark task N as done by inserting @Done after @Task
• streamd todo --show-future — Include tasks with future dates in the listing
• streamd edit [number] — Edit a stream file by index (most recent first)
• streamd timesheet — Generate time reports from @Timesheet markers
• streamd lsp — Start the LSP server (stdin/stdout transport; see Editor Integration below)

Configuration

User Configuration

Streamd reads its user configuration from ~/.config/streamd/config.toml (XDG standard). The main setting is base_folder, which points to the directory containing your stream files (defaults to the current working directory).

Repository Configuration

For timesheet reporting, create a .streamd.toml file in your stream files directory:

timezone = "Europe/Berlin"  # Optional: timezone for day boundaries

[timesheet]
[[timesheet.periods]]
start = "2026-01-01"
end = "2026-06-30"
hours_per_week = 38.0

[[timesheet.periods]]
start = "2026-07-01"
end = "2026-12-31"
hours_per_week = 40.0

The timesheet command will calculate expected vs actual working hours based on these periods, showing:

• Daily breakdown with expected/actual hours
• Special day types (sick leave, vacation, holidays, flex days)
• Warnings for missing entries and overlapping timecards
• Monthly and cumulative balance

Usage

Running streamd opens your editor to create a new entry. After saving, the file is renamed based on its timestamp and any markers found in the content.

Running streamd todo finds all shards marked as open tasks and displays them numbered in your terminal. Tasks with future dates are hidden by default (use --show-future to include them). Tasks are sorted by date with oldest first (task 1 is the oldest).

You can quickly edit or complete tasks by number:

• streamd todo 1 edit opens task 1 in your editor at the correct line
• streamd todo 1 done marks task 1 as done by inserting @Done after @Task

Editor Integration

streamd lsp starts a Language Server Protocol server that provides IDE features for your stream markdown files. The server communicates over stdin/stdout and auto-activates only when a .streamd.toml file is present in the workspace root.

Features

Feature	Description
@ completions	Suggests known markers from your config; conditional suggestions (e.g. @Done when @Task is on the line)
Temporal snippets	@ followed by a digit offers YYYYMMDD / HHMMSS format snippets
Diagnostics	File-name format warnings (R15); timesheet errors (overlapping timecards, unclosed days)
Document symbols	Shard tree exposed as outline symbols
"Mark task as done"	Quick-fix code action: inserts @Done after @Task
Workspace symbols	Search shards across all .md files
References	Find all occurrences of an @Marker across the workspace
Rename	Rename an @Marker across all files

Zed

Add to ~/.config/zed/settings.json:

{
  "languages": {
    "Markdown": {
      "language_servers": ["streamd-lsp", "..."]
    }
  },
  "lsp": {
    "streamd-lsp": {
      "binary": {
        "path": "streamd",
        "arguments": ["lsp"]
      }
    }
  }
}

The "..." keeps Zed's default Markdown servers (e.g. marksman) active alongside streamd.

Neovim (nvim-lspconfig)

1. Register the server — add to your Neovim config (e.g. ~/.config/nvim/init.lua or a plugin file):

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

if not configs.streamd then
  configs.streamd = {
    default_config = {
      cmd = { 'streamd', 'lsp' },
      filetypes = { 'markdown' },
      root_dir = lspconfig.util.root_pattern('.streamd.toml'),
      single_file_support = false,
    },
  }
end

lspconfig.streamd.setup {}

The server activates automatically when Neovim opens a Markdown file inside a directory that contains a .streamd.toml file.

2. Using LSP features — standard Neovim LSP keymaps apply (:help lsp):

Action	Default keymap	Notes
Trigger @ completions	<C-x><C-o> (insert mode)	Or via your completion plugin (nvim-cmp, blink.cmp, …)
Show diagnostics for current line	<C-w>d / gl	File-name format warnings, timesheet errors
Jump to next / previous diagnostic	]d / [d	Navigate between warnings
Code actions (mark task as done)	<leader>ca (Neovim ≥ 0.10)	Place cursor on a line with @Task
Rename marker across all files	<leader>cr / grn	Renames the @Marker under the cursor everywhere
Find all references to a marker	grr / <leader>fr	Lists every occurrence of @Marker across the workspace
Document outline (shard tree)	:lua vim.lsp.buf.document_symbol()	Or via Telescope: :Telescope lsp_document_symbols
Workspace symbol search	:lua vim.lsp.buf.workspace_symbol()	Or via Telescope: :Telescope lsp_workspace_symbols

Note: default keymaps (grn, grr, <C-w>d, ]d/[d) are available from Neovim 0.10+. On older versions use :lua vim.lsp.buf.* commands or set up keymaps manually in your on_attach callback.

VS Code (tasks.json / manual)

Use any extension that lets you configure custom LSP servers, pointing cmd to streamd lsp.