Web App — Remote Access, Zero Install​

UnDercontrol's web frontend is built with Vite + React + TypeScript and serves as the foundation of the entire platform. Open a browser and you're in — no installation required.

Core capabilities:

• Full task, budget, and expense management
• Tiptap rich-text editor (code blocks, Mermaid diagrams, tables, checklists)
• AI chat integration (supports Claude, OpenAI, and other providers)
• SSE real-time notifications with multi-tab sync
• Responsive design that works on mobile
• Bilingual interface (Chinese / English)

The web app also serves as the rendering layer for the Electron desktop app — same codebase, zero duplication.

Typical scenarios

• On the go, quickly check task progress or approve expenses from your phone's browser
• Team members collaborate instantly — just open a link, no software to install
• The convergence point for all clients — docs pushed from CLI, tasks created on desktop, pages clipped by the extension — all viewable and manageable in one place

Electron Desktop App — Offline First, Local Data​

The desktop app is far more than a web wrapper. It embeds a full Go backend and SQLite database, ready to use out of the box with no server configuration.

Embedded backend architecture

• Automatically launches the Go backend on startup
• Dynamic port allocation to avoid conflicts
• Data stored in ~/Library/Application Support/UnDercontrol/ (macOS)
• Fully offline-capable — works without any network connection

Remote backend mode

• The desktop app can also connect to a remote server, sharing the same data source as the web app
• Switch the API address in settings — no reinstallation needed

Daemon mode

• Background daemon process that listens to the task queue via SSE
• Receives and automatically executes remotely dispatched tasks — ideal for AI Agent workflows

Desktop-exclusive features

• System tray (Windows) — minimize to tray for quick access
• .md file association — double-click a Markdown file to open it in UnDercontrol
• Multi-window editing — open multiple editor, task, and sticky-note windows simultaneously
• Workspace management — local terminal windows for running commands

Build targets

• macOS — DMG installer, Universal Binary (x64 + ARM64)
• Windows — NSIS installer (x64)
• Linux — AppImage (x64)

Typical scenarios

• On a plane or train with no network — create tasks and edit documents as usual; everything syncs when you're back online
• At home, connect the desktop app to your company server — see exactly the same data as the web app
• Receive remotely dispatched AI tasks via Daemon and execute them automatically on your local machine

CLI — kubectl-Style, AI Agent Friendly​

The ud CLI is a terminal tool designed for developers and automation, using a kubectl-style verb-resource command system.

Interactive TUI

Run ud to enter a full-screen TUI for browsing and managing tasks with your keyboard.

One-liner operations

ud get task                          # list tasks
ud describe task abc123              # view details
ud apply -f task.md                  # create/update from file
ud task query "status:todo tag:api"  # query and filter
ud task nl "tasks completed last week" # natural language query

AI Agent integration

ud prompt <skill-name> outputs skill documents that teach AI Agents (Claude Code, Codex, OpenCode, and others) how to operate tasks via the ud CLI. Structured command output and Markdown-formatted input make it a natural fit for AI Agents to read and write.

Typical scenarios

• CI/CD pipelines automatically push release notes to ud — the team reads them on the web, no need to dig through Git logs
• Technical docs in your code repo (architecture designs, API specs, runbooks) are synced to ud via scripts — non-developers can read them on the web without accessing the repository
• AI Agents automatically record progress and decisions in task notes during coding — the team sees updates in real time
• Ops scripts periodically collect inspection results and ud apply them as tasks, forming a traceable operations log

Chrome Extension — One-Click Clipping​

The Chrome extension turns any web page into an UnDercontrol task.

• One-click save — captures a full page snapshot (HTML + all embedded resources)
• Markdown extraction — automatically extracts the page body as clean Markdown
• Offline mode — save directly to local disk without logging in
• Remote mode — log in to create an UnDercontrol task directly, with the snapshot uploaded as an attachment

Typical scenarios

• Researching competitors — clip product pages as tasks, then compare and organize on the web later
• Found a great technical article — clip it as Markdown into ud for the team to share
• Received a customer bug report on a web page — clip it as a bug task with full context attached

SSE Real-Time Sync​

All clients connected to the same backend — whether browser tabs, the desktop app, or another device — stay in sync via SSE (Server-Sent Events).

• Task status changes, new comments, attachment uploads — all events pushed in real time
• Daemon SSE Hub dispatches commands to desktop Daemon instances
• Workspace session state is automatically coordinated between the desktop app and the backend

One Codebase, Consistent Experience​

UnDercontrol's multi-platform strategy isn't "build once for each platform." Instead:

• Web app is the single frontend codebase
• Electron loads the web build directly — zero code duplication
• CLI shares the same API and data model
• Chrome extension uses the same API endpoints

And there's more — the open API lets you build any client you want.

Beyond Official Clients — Build Your Own​

Beyond the four official clients, UnDercontrol exposes a full RESTful API. Generate an API Key in your profile settings, pair it with the Swagger docs, and build your own client in any language — Python scripts, automation bots, internal tool integrations, or even your own mobile app.

• API Key authentication — generate in Profile → API Key, call with Bearer Token
• Scoped permissions — authorize independently by module (Tasks, Expenses, Budgets, Files, AI)
• Swagger docs — browse all endpoints at https://your-server/swagger/index.html
• X-UD-Channel audit — custom channel identifier to trace every request's origin
• CI/CD friendly — environment variable configuration for seamless automation pipeline integration

Typical scenarios

• Build a Slack Bot in Python — your team types /task in Slack to create and query ud tasks
• Connect your internal admin panel's ticketing system to ud via API for bidirectional status sync
• Build a native mobile app calling the same API for a personalized phone experience
• Monitoring system alerts automatically create ud tasks with context attached — on-call engineers handle them on the web

Different scenarios, the right tool for the job — data always in sync, experience always consistent.

In UnDercontrol, a Task is the core unit of information. If you've used Jira, think of it as an Issue; if you've used Obsidian, think of it as a Note. A Task is essentially a piece of content bound to a status, with first-class attributes (title, tags, link relationships, etc.) and support for unlimited custom metadata fields (key-value pairs), so you can attach any information to it. Through the Notes mechanism, a Task can continuously evolve — recording progress, discussions, and decisions, accumulating into a complete knowledge context over time.

This post covers the rich-text capabilities shared across all text input surfaces in UnDercontrol. We say "tasks", but it's not just tasks — whether it's a task description, a note, an expense memo, or an account annotation, they all use the same Markdown editor. The code blocks, Mermaid diagrams, tables, and checklists you use in tasks work identically in notes and every other context.

WYSIWYG — A Markdown Editor Built on Tiptap 3​

UnDercontrol's editor is built on Tiptap 3. You can write directly in Markdown syntax or use the visual toolbar — the editor renders in real time, what you write is what you see. No switching between "edit mode" and "preview mode" — the input is the final output.

The editor also supports switching to Source Mode to view and edit the raw Markdown directly — for users who prefer plain text editing or need precise format control, you can freely toggle between WYSIWYG and raw Markdown at any time.

Slash Commands — Format Without Leaving the Keyboard​

Type / anywhere to open the command menu. Insert headings, code blocks, tables, Mermaid diagrams, checklists, and more — all without touching the mouse.

The slash menu supports:

• Headings (H1–H5) for document structure
• Task lists with interactive checkboxes
• Code blocks with language selection and syntax highlighting
• Mermaid diagrams for flowcharts, sequence diagrams, and more
• Tables with full cell editing
• Blockquotes, dividers, and images

Syntax-Highlighted Code Blocks​

Paste code snippets directly into your tasks. The editor supports 100+ programming languages with proper syntax highlighting — from TypeScript and Go to SQL and YAML.

Code blocks include a language selector dropdown and a one-click copy button. Your code stays readable and properly formatted, whether you're documenting an API endpoint or saving a useful shell command.

Mermaid Diagrams — Visualize Architecture Inline​

One of the most powerful features: embed Mermaid diagrams directly in your task descriptions. Insert a Mermaid block via the slash menu, write your diagram syntax, and it renders live.

Supported diagram types include:

• Flowcharts — system architecture, decision trees
• Sequence diagrams — API flows, authentication handshakes
• Class diagrams — data models, entity relationships
• State diagrams — workflow states, lifecycle tracking

The diagram viewer supports fullscreen preview, SVG download, and automatic dark/light theme switching.

Tables for Structured Data​

Need to document status codes, compare metrics, or track a feature matrix? Insert a table and edit cells directly. Add or remove rows and columns, toggle header rows, and merge cells — all from a context menu.

Checklists That Actually Work​

Task lists render as interactive checkboxes. Check items off directly in the rendered view — no need to switch to edit mode. Great for tracking sub-steps, acceptance criteria, or deployment checklists.

Images & Attachments — No More Obsidian-Style Resource Management Headaches​

If you've managed notes with images in Obsidian, you've probably experienced the pain: images scattered across local folders, paths break when you move things, attachments disappear on another device, multi-device sync creates endless conflicts. The root cause — Obsidian delegates resource management to the filesystem, and filesystems are inherently bad at cross-device sync.

UnDercontrol solves this at the foundation. All images and attachments are managed through the resource:// protocol — upload once, stored in the database, no dependency on local paths. Whether you view content on the web, desktop, or via a shared link, images are always available — because resources follow the database, not the filesystem.

UnDercontrol also provides bidirectional local folder sync, keeping files in a local directory synchronized with the server resource library. We'll cover this feature in detail in a future post.

Image Size Control

Inserted images support three size presets — hover in edit mode to switch:

• Small (25%) — thumbnail, suitable for inline display
• Medium (50%) — moderate size
• Large (100%) — full width

Size information is stored in Obsidian-compatible format (![description|s](resource://id)). Click any image for fullscreen preview.

Draw.io Diagrams — Built-in Visual Drawing​

UnDercontrol includes a built-in Draw.io editor, supporting .drawio and .drawio.png formats. Upload or create a Draw.io file, then edit it directly in the app — no desktop software needed. Saved as PNG with embedded XML source data, so it renders as a preview and can be re-edited at any time.

Thanks to the resource:// protocol, Draw.io diagrams are managed as unified resources — no local path dependencies or sync issues.

AI-Powered Text Actions​

Select any text to reveal the bubble menu. Beyond standard formatting (bold, italic, strikethrough), you get AI-powered actions:

• Refine — rewrite selected text for clarity
• Translate — translate to another language instantly
• Chat — ask questions about the selected content

Entity Links — Connect Tasks Like a Wiki​

Link to other tasks, notes, expenses, budgets, and accounts directly in your descriptions using custom protocols like task://, note://, and more. The links render as clickable references — click to jump straight to the referenced entity.

Switch to source mode to see the raw markdown — each link uses a custom protocol like [API Integration Guide](task://189571b0-...):

This turns your task descriptions into a connected wiki, where context flows naturally between related items.

CLI + AI Agent — Let AI Write Your Content​

Because Markdown is plain text, it's a natural fit for AI agent collaboration. Through the ud CLI, you can let Claude Code, Codex, OpenCode, or any terminal-based AI tool read, write, and update task content directly:

• Summarize — have AI read a set of tasks and generate a weekly report or sprint review
• Refine & restructure — turn scattered notes into structured documentation
• Classify & tag — automatically add tags and categories based on content
• Batch create — generate multiple tasks from meeting notes or requirement docs

Content pipes directly in:

cat <<'EOF' | ud apply -f -
---
title: API Integration Guide
status: in-progress
tags: [api, backend]
---
## Authentication Flow

1. Client sends credentials to `/auth/login`
2. Server returns JWT token
3. Include in `Authorization: Bearer <token>` header
EOF

AI-generated Markdown renders identically to hand-written Markdown across web, desktop, and shared views. Your content stays portable and version-controllable.

Markdown support in UnDercontrol means your tasks can be as detailed and technical as they need to be — without leaving the tool where the work gets tracked. Code blocks, diagrams, tables, and checklists all live alongside your task status, deadlines, and collaboration context.

Try it out — create a task and type / to see what's possible.

That's Remote Workspace. It bridges the gap between a cloud-based task manager and your local development environment, turning UnDercontrol into a remote control for AI-powered coding agents.

The Problem​

Most task management tools live entirely in the browser. Your code lives on your machine. When you want an AI agent to work on something, you switch to a terminal, paste context, babysit the process, and manually update the task when it's done. The task tracker and the execution environment are two separate worlds.

Remote Workspace collapses that distance. Your task descriptions become executable instructions. Your browser becomes a control panel. Your machine does the work.

How It Works​

The architecture has four pieces:

1. The Electron Desktop App — runs on your machine and acts as the daemon. When you register your device in the Workspaces page, the app connects to the UnDercontrol server via Server-Sent Events (SSE) and waits for instructions.

2. The Server — relays commands between the web UI and the daemon. Persists session state, notes, and status updates.

3. The Daemon Core — the "brain" inside the Electron renderer. It holds auth tokens, manages SSE connections, and drives all API calls. When a workspace session starts, it forwards the init event to the Electron main process.

4. The AI Agent — a coding tool (like Claude Code) spawned in a pseudo-terminal by the Electron main process. It reads the task, does the work, and reports progress through task notes.

Setting It Up​

Open the UnDercontrol desktop app and navigate to the Workspaces page. Click Register this device — the app detects your machine name and platform automatically. That's it. Your machine is now a daemon, connected and ready.

The Electron app handles everything behind the scenes: daemon registration, SSE connection, heartbeat, and reconnection. No terminal commands needed.

For the AI agent to work, you'll need Claude Code installed on your machine:

npm install -g @anthropic-ai/claude-code

Triggering a Session​

Once your device is registered and online, go to any task in the web UI (or the desktop app itself). Click the globe icon in the actions bar. You'll see a list of your connected daemons — pick one, and the session starts.

The daemon receives the init event, and the Electron main process spawns the AI agent in a PTY window. From this point, everything happens automatically:

1. The agent reads the task description and notes
2. It plans and executes the work
3. Progress notes appear on the task in real-time
4. When done, it updates the task status

Watching It Work​

This is where it gets satisfying. As the agent runs on your machine, you see its progress in the browser — live.

Notes stream in as the agent works: what it's reading, what it changed, which files it committed. You get a running log of the entire session without touching the terminal.

The session panel shows:

• Status — running, planning, awaiting input, idle, or stopped
• Duration — how long the session has been active
• Daemon info — which machine is doing the work
• Notes stream — real-time updates from the agent

Interactive Control​

Remote Workspace isn't fire-and-forget. You can interact with the agent while it's running:

• Send instructions — type additional context or redirect the agent mid-task
• Take screenshots — capture the current state of the workspace
• Interrupt — send a Ctrl+C signal to pause execution
• Stop — end the session entirely

There's also a prompt system. Save frequently-used instructions as templates, and apply them with one click. If you've set up skills in UnDercontrol, you can reference those too — pipe a skill's content directly to the agent.

The Workspaces Dashboard​

The Workspaces page gives you a bird's-eye view of all active sessions and connected daemons.

Each session card shows the task it's working on, which daemon is running it, how long it's been going, and the latest notes. Daemons are listed with their online/offline status, machine name, platform, and sharing permissions.

You can register your device right from this page — one click and you're online.

Security​

Running AI agents remotely raises obvious safety questions. Remote Workspace handles this with a layered blacklist system:

Built-in protections:

• Tools like bash, sh, zsh are blocked as the implementation tool — the agent runs through a controlled interface, not a raw shell
• Destructive commands (rm -rf, mkfs, dd) are blocked at the daemon level

Custom configuration: Drop a YAML file at ~/.config/ud/workspace-blacklist.yml to define your own rules:

blocked_tools:
  - bash
  - sh
allowed_tools:
  - claude
blocked_commands:
  - "rm -rf"
  - "mkfs"

The daemon also requires proper authentication — the Electron app uses your logged-in session tokens, so unauthorized access isn't possible without your credentials.

Sharing Daemons​

In team setups, you can share a daemon with your group. Set the sharing permissions so teammates can trigger workspace sessions on your machine — useful for shared build servers or dedicated CI machines.

Sharing is controlled through the daemon's permissions: read-only lets others see the daemon status, read-write lets them initiate sessions.

Why This Matters​

Most developer tools treat task management and code execution as separate concerns. You plan in one app, execute in another, and manually bridge the gap with copy-paste and context switching.

Remote Workspace merges them. Your task description is the instruction. Your browser is the control panel. The work happens on your machine, with your tools, in your environment — you just don't have to be in the terminal to start it.

For solo developers, it means less context switching. Write the task, trigger the agent, review the output — all in the same interface. For teams, it means a shared queue of work that machines can pick up and execute, with full visibility into what's happening.

The architecture also means you're not locked into any particular AI tool. Today it works with Claude Code; tomorrow it could work with any agent that runs in a terminal. The protocol is simple: receive a task, do the work, report progress.

Getting Started​

1. Download the UnDercontrol desktop app
2. Install Claude Code: npm install -g @anthropic-ai/claude-code
3. Open the Workspaces page and click Register this device
4. Open any task, click the globe icon, and select your daemon

Check the documentation for the full setup guide, including security configuration and troubleshooting.

UnDercontrol's task sharing solves this exact problem. Generate a public link, hand over a short access code, and anyone can view that specific task — your description, notes, attachments, the whole thing — without needing an account or touching your credentials.

How It Works​

From any task detail page, click the share icon to open the share dialog. You get two things:

1. A direct link — a full URL that opens the task in a clean, read-only view
2. An access code — a short alphanumeric code (like QJVOFL) that someone can type into the share code page

The access code is designed for situations where you can't easily send a link — like telling someone over the phone, writing it on a whiteboard, or dropping it in a chat where long URLs get mangled.

Control What Gets Shared​

Not every task should be shared the same way. The share dialog gives you two controls:

Expiration: Choose how long the link stays active. Options range from 1 hour (for quick look-overs) to 7 days (for ongoing collaboration) to never (for permanent reference links).

Attachment access: By default, attachments are listed but not downloadable. Toggle "Allow attachments" if you want viewers to download files attached to the task.

You can create multiple share links for the same task with different settings — maybe a 1-hour link for a quick review and a 7-day link for a collaborator.

The Viewer Experience​

When someone opens a shared link, they see a clean, focused view of the task:

• Title and status with the familiar status icon
• Tags for context
• Full markdown description rendered with all formatting, tables, and images
• Notes sorted by most recent, also fully rendered
• Attachments (downloadable if the link allows it)
• Linked items shown as references
• QR code in the corner for easy re-sharing on mobile
• Expiration countdown so viewers know how long the link is valid

The page is self-contained. No navigation chrome, no login prompts, no app shell. Just the content.

Access Codes — The Analog Bridge​

The access code feature deserves its own mention. Navigate to the share page (/share), type in the code, and you're redirected to the shared task.

This is particularly useful for:

• Presentations: Put the code on a slide, let the audience look up the reference material
• Phone calls: "Check out task code QJVOFL" is easier than reading a 60-character URL
• Physical spaces: Write the code on a sticky note or whiteboard

Managing Share Links​

Back in the share dialog, you can see all active links for a task. Each entry shows:

• The access code and a truncated token
• Whether attachments are enabled (paperclip icon)
• When it expires (relative time)

Revoke any link instantly with the delete button. The shared view will immediately show an error for anyone who tries to access it.

Under the Hood​

Sharing is token-based. Each share link gets a unique token that maps to the task. The public endpoint (/share/todolist/:token) requires no authentication — it's a true public route. Resources embedded in the markdown description (images, diagrams) are resolved through the share token too, so inline images render correctly without exposing your storage credentials.

The access code is a separate entity that maps to the token, providing an additional access path without compromising security. Codes are uppercase alphanumeric for readability.

When to Use This​

A few scenarios where task sharing shines:

• Cross-team handoffs: Share a requirements doc with someone outside your organization
• Client updates: Send a project status task to a client without giving them app access
• Meeting prep: Share an agenda task before a meeting via access code
• Knowledge sharing: Create a permanent link to a reference document or runbook
• Quick reviews: Generate a 1-hour link for a quick peer review

The key insight is that not every piece of information needs to live behind a login wall. Sometimes you just need to show someone a thing, quickly, without friction.

Task sharing is available now in UnDercontrol. Open any task, click share, and try it out.

The Four Levels​

Here is the mental model: each filter level narrows what the previous level passed through. Think of it as a pipeline.

Level 1: Board Scope (private vs shared) → Level 2: Scope Tags (board-level tag filter) → Level 3: Column Query (per-column conditions) → Level 4: Ephemeral Filter (search, tags, assignees in the toolbar)

Let us walk through each one.

Level 1: Board Scope — Who Sees What​

This is the implicit layer. When you create a board, you choose between private and shared.

• Private boards show all tasks you have access to — your own tasks plus tasks others have shared with you. This means tasks from multiple people can appear together on one board, giving you a single place to see everything relevant to you. Only you can see this board and its arrangement.
• Shared boards are tied to a group. The board only shows tasks that belong to that group, and everyone in the group can see and interact with it based on their permissions.

You do not configure this as a "filter" — it is baked into the board's identity. But it is the first gate that determines which tasks are even candidates for display.

The private board model is particularly useful when several people share tasks with you individually. Instead of jumping between different sources, you see all of them in one kanban view — your own work alongside tasks shared by teammates, collaborators, or managers.

Level 2: Scope Tags — Narrowing the Board's Focus​

This is where things get powerful. Each board can have scope tags (also called default tags) — a set of tags that act as a persistent filter for the entire board.

When you set scope tags on a board:

1. Only tasks with ALL specified tags appear on the board
2. New tasks created on the board automatically get these tags, so they match the filter from the start

For example, a "Sprint 1" board with scope tag sprint-1 will only show tasks that have the sprint-1 tag. Your "All Tasks" view might show 40+ tasks across all sprints, but the Sprint 1 board shows only the 8 that matter right now.

This is configured in Settings → Edit Board Details → Scope Tags.

The key insight: scope tags create a named, persistent view over your task pool. You can have a "Frontend" board (scope tag: frontend), a "Sprint 2" board (scope tag: sprint-2), and they all draw from the same tasks. Change a task's tags and it automatically appears or disappears from the relevant boards.

Level 3: Column Query — Sorting Tasks into Lanes​

Within each board, every column has its own match condition — a query that determines which tasks land in that column.

The most common pattern is filtering by status:

• To Do column: Status = 'todo'
• In Progress column: Status = 'in-progress'
• Done column: Status = 'done'

But columns can use any field and operator. You could create a column for tags CONTAINS 'urgent', or cf.priority >= '3', or combine multiple conditions with AND/OR logic.

The powerful part: columns also have auto-actions. When you drag a task into a column, its conditions are applied automatically. Drag a task into "Done" and its status changes to done. Drag it into a column filtered by tags CONTAINS 'reviewed' and the tag gets added. The board does the bookkeeping.

Level 4: Ephemeral Board Filter — Real-Time Refinement​

The top toolbar provides three real-time filters that layer on top of everything else:

• Search: Type in the search bar to filter by task title across all columns
• Tags: Click the Tags button to select one or more tags — only tasks with ALL selected tags appear
• Assignees: Filter by who is assigned to the task

These filters are ephemeral — they do not modify the board permanently. Close the tab and they are gone. But they are URL-persisted: the filter state is encoded in the URL as query parameters like ?tags=backend&search=API.

This means you can bookmark a filtered view, or share the URL with a teammate to show them exactly the subset of tasks you are looking at.

How the Levels Combine​

Here is a concrete example showing all four levels working together:

1. Board Scope: You open your private "Sprint 1" board
2. Scope Tags: The board has scope tag sprint-1, narrowing from 40+ tasks to 8
3. Column Query: The "In Progress" column shows status = 'in-progress', narrowing to 3 tasks
4. Ephemeral Filter: You type "API" in the search bar, narrowing to 1 task — "Update API documentation"

Each level operates independently. You can change any layer without affecting the others. Switch the scope tags and the columns still work. Apply a search filter and the column queries remain unchanged.

Practical Patterns​

Sprint planning: Create a board per sprint with the sprint tag as scope tag. All sprints share the same tasks, but each board shows only its sprint.

Cross-cutting views: A "Frontend" board and a "Backend" board can both show tasks from Sprint 1 and Sprint 2 — they just use different scope tags. A task tagged frontend + sprint-1 appears on both the Frontend board and the Sprint 1 board.

Quick triage: Use ephemeral filters to zoom into a specific area during a standup. Filter by assignee to see what each person is working on, then clear the filter to see the full picture.

Complex columns: Instead of simple status columns, create columns like "Blocked Backend" (status = 'in-progress' AND tags CONTAINS 'blocked' AND tags CONTAINS 'backend') for specialized workflow views.

The Filter is the Control​

This layered approach follows one of UnDercontrol's core design principles: the filter is the control. You are not navigating through menus to manage what appears where. The board's scope tags, each column's query, and the toolbar's search and tag badges are all visible, interactive, and directly editable. You can see exactly what is filtering your view, and change it with a click.

The URL-persisted ephemeral filter takes this further — your current view state is always shareable and bookmarkable, turning a transient search into a reusable link.

The problem is those prompts live in your head, or a sticky note, or buried in a Notion doc nobody remembers to open. UnDercontrol's skills system fixes that.

What Are Skills?​

Skills are named, reusable prompt templates stored inside UnDercontrol. Each skill has a slug (e.g., refactor-ts, daily-standup, pr-review), a markdown body, and belongs to a group. That last part matters — skills are group-scoped, so a team can share a library of prompts without everyone maintaining their own copy.

You can create and edit skills through the web UI, manage them from the CLI, or apply them declaratively from a YAML file. The markdown content supports the full range of prompt structures: instructions, variables, multi-step workflows, whatever your use case needs.

Creating a Skill​

From the web editor, creating a skill is about as straightforward as writing a note. Give it a name, a slug, and write your prompt in the markdown editor. Save it, and it's immediately available to everyone in the group.

From the CLI, you can apply a skill definition the same way you'd apply a task — as a markdown file with YAML frontmatter:

ud apply skill -f pr-review.md

Your file might look like this:

---
name: pr-review
description: PR Review Checklist
tags:
  - ai
  - development
---

Review the following pull request diff and provide feedback on:
- Logic correctness
- Error handling
- Test coverage
- Naming and readability

This makes skills portable. Check them into your dotfiles repo, version them with the rest of your configuration, and deploy them to a new UnDercontrol instance with a single command.

Using a Skill — The ud prompt Command​

The real payoff is how you consume skills. The ud prompt command fetches a skill by slug and outputs its content to stdout. From there, you can pipe it anywhere.

Want to feed a skill into Claude Code?

claude-code $(ud prompt pr-review)

Want to compose it with other commands in a pipeline?

ud prompt pr-review | pbcopy

Because it's just stdout, ud prompt works with any tool that reads from stdin — Claude Code, other local AI agents, shell pipelines, whatever fits your workflow. UnDercontrol doesn't try to own the AI layer; it just manages the prompts so you don't have to.

Built-in System Skills​

UnDercontrol ships with built-in system skills that are seeded on first startup. These are read-only — you can't accidentally overwrite them — and they serve as both useful defaults and examples of how skills are structured. The ud-cli system skill, for instance, provides a comprehensive reference for the CLI's command structure, making it immediately available to AI agents that need to interact with your tasks.

System skills are marked with a lock icon in the web UI and appear alongside your custom skills. You can reference them by slug just like any custom skill.

Managing Skills Over Time​

Skills are first-class resources in UnDercontrol, which means full CRUD support through both the web UI and the CLI.

• ud get skills — list all skills in your group
• ud describe skill <id> — inspect a specific skill's full content
• ud delete skill <id> — remove one you no longer need
• ud apply skill -f skills/ — apply an entire directory of skill definitions at once

The web editor is useful for quick edits and browsing what's available. The CLI is better for automation, bulk updates, and treating your prompt library as code.

Why This Matters​

The idea behind skills is simple: the prompts that work well are worth keeping. Storing them in a self-hosted, group-scoped system means they don't disappear when someone leaves the team, don't get lost in a chat history, and don't require everyone to reinvent the same workflow independently.

It also keeps your prompts private. Because UnDercontrol is self-hosted, your prompt library — which often encodes institutional knowledge, internal processes, and domain-specific context — stays on your own infrastructure.

Get Started​

Skills are available in UnDercontrol today. If you're already running an instance, you'll find the Skills page in the sidebar. If you're setting up for the first time, the self-hosting guide walks through deployment in about ten minutes.

Read the documentation or deploy your own instance to get started.

The 5-Second Navigation Freeze​

The most impactful fix was a navigation regression where clicking a task from the kanban board froze the UI for up to 5 seconds.

The root cause was subtle. A previous optimization eagerly pre-loaded the TaskDetail chunk so that React.lazy() resolved instantly. This sounds like it should be faster, but it had the opposite effect: without the brief Suspense pause, React committed the route change synchronously. That meant unmounting the entire kanban board — hundreds of sortable items, drag-and-drop contexts, all of it — in one blocking frame before the new page could even start mounting.

With standard lazy loading, the first navigation triggers a short Suspense boundary. React Router uses a transition that keeps the old page visible while the new chunk loads, and cleanup happens non-blockingly in the background. Subsequent navigations use the cached chunk anyway.

The fix: revert to standard React.lazy() and let the framework do what it's designed to do.

Backend: Fixing N+1 Queries on Task Detail​

The GET /todolist/:id endpoint had two problems:

1. Duplicate queries — enrichItem() called loadRelatedData() to fetch notes and share links, but GetByIDEnriched() already loaded those same relations. Every request ran 2 redundant queries.

2. N+1 on linked items — each linked task was fetched individually in a loop. A task with 5 linked items meant 5 separate SELECT statements.

After the fix, a task detail request runs 4 queries total (main record + notes + share links + one batch WHERE id IN (...) for linked items), down from 7+ before.

Lazy Note Editors with IntersectionObserver​

Tasks in UnDercontrol can have many notes, each rendered with a TipTap rich-text editor. Every TipTap instance creates DOM nodes, event listeners, and extension chains — initializing 10 of them on page mount adds up fast.

Now only the first 2 notes render their editors immediately. The rest show a lightweight placeholder until they scroll within 200px of the viewport. On a task with 10 notes, this avoids initializing 8 editor instances upfront.

No More Flash When Switching to Edit Mode​

Toggling a note from read mode to edit mode used to produce a brief white flash. Two things caused it:

• TipTap's default behavior waits a frame before rendering content
• Resource URLs (resource://...) were resolved before setting any content, so the editor was empty until async resolution completed

The fix sets immediatelyRender: true on the editor and loads raw markdown content synchronously first. Resource images resolve in the background — you see the text instantly, and images fill in a moment later. If the content has no resource:// URLs at all, the processing step is skipped entirely.

Editor Toolbar Fixes​

A few smaller but annoying editor issues were resolved:

• Toolbar frozen on horizontal scroll — the formatting toolbar used fixed positioning, so scrolling right left it stuck at x=0. Switched to sticky so it scrolls with its container.
• Toggle button scrolls away — on long notes, the edit/preview toggle button scrolled out of view. It's now pinned in a sticky action bar.
• Mobile action bar overlap — on mobile, the editor action bar sat behind the floating chat button. Raised it to clear the obstruction.

China Download Mirror​

For users in mainland China, downloading the desktop app from our default CDN (Cloudflare R2) can be slow or unreliable. We added a 中国大陆下载 button in the download dialog that pulls from Bitiful, a China-based CDN. Download metrics track which mirror was used so we can monitor adoption.

The release pipeline now automatically uploads builds to both R2 and Bitiful, and cleans up old versions on Bitiful (keeping the latest 2) to manage storage.

These changes are available in v0.65.2. If you're self-hosting, pull the latest image and you're set.

The best part? You're still self-hosted. You're not handing your data to a third-party service to enable multi-user workflows.

How Groups Work​

A group in UnDercontrol is a shared workspace. Think of it as a container for people who need to see or work on the same things together. Common setups include a family tracking a shared budget, a small team coordinating project tasks, or two people splitting household expenses.

Creating a group takes about ten seconds: give it a name, add a description, and you're the owner. From there, you generate invite links to bring people in.

Invite links are flexible. You can set an expiration date so a link becomes invalid after a day or a week — useful when you're adding a temporary collaborator. You can also revoke any link at any time. It's a small detail, but it matters when you care about who has access to your workspace.

Role-Based Permissions​

Once people are in a group, roles determine what they can do. There are three group-level roles:

• Owner — full control over the group, including members, settings, and all shared content
• Admin — can manage members and invites, access all shared content
• Member — can view and interact with shared resources based on the permission level set on each item

Beyond group roles, UnDercontrol also has system-level roles: Admin, User, and Visitor. If you're running a self-hosted instance for a small organization, you can create custom roles with specific permission sets covering tasks, expenses, budgets, files, and more. This is the kind of access control you'd expect from enterprise tools, available in a self-hosted app you run yourself.

Sharing Tasks with the Right Level of Access​

When you share a task with a group, you choose the permission level: read-only or read-write.

Read-only is useful when you want someone to stay informed without being able to modify anything — a manager reviewing a task list, for example, or a partner who needs to see what's on the agenda without accidentally editing it.

Read-write sharing enables real collaboration. Group members can update the task, check off items, and work alongside you. Shared tasks show up in each member's task list, so nothing gets buried.

Files attached to a shared task are automatically accessible to group members. There's no separate file-sharing step — if you've attached a PDF or an image to a task, everyone with access to that task can see it.

Kanban Boards and Shared Workflows​

Shared kanban boards integrate directly with the group system. When you create a shared board, it automatically creates a group behind the scenes. The board creator becomes the group admin, and collaborators join as members. This means your team's workflow is always tied to a proper access model — not just an open link that anyone can stumble into.

Practical Tips​

A few things worth knowing before you set up your first group:

Currently, each user can belong to one group at a time, so think about how you structure your workspace. If you're coordinating a work project and a household budget, the people involved will need to choose which group they're part of — or you handle both under a single group with clear task naming conventions.

Use descriptive group names from the start. "Family Budget 2026" or "Backend Team Q2" is far more useful three months later than "My Group."

Set expiration dates on invite links whenever you're adding someone for a limited purpose. It takes two extra seconds and removes the need to remember to revoke the link later.

Review your member list occasionally. People change roles, projects end, living situations shift. Keeping the member list current is basic hygiene for any shared workspace.

Get Started​

If you already have a self-hosted instance running, head to the Groups page and create your first group. If you haven't set up UnDercontrol yet, the self-deployment guide walks through the full setup — you can be running in under an hour with Docker.

The collaboration documentation covers every feature in detail, including the full permission system and how groups interact with budgets and resources.

That kind of real-time sync sounds simple but gets complicated fast when you factor in reconnects, offline states, and the cost of keeping connections alive. Here is how UnDercontrol handles it.

Why Server-Sent Events​

WebSockets are the obvious choice for real-time features, but they come with overhead — bidirectional connections, custom protocol handling, and more complexity on both ends. For UnDercontrol, the update flow is almost entirely one-directional: the server pushes changes down to clients. That maps perfectly onto Server-Sent Events (SSE), which is a standard HTTP mechanism built into every modern browser.

SSE gives us persistent connections over plain HTTP, automatic reconnection built into the browser spec, and no additional infrastructure beyond the Go backend that already runs your instance. It keeps the self-hosted model clean.

How It Works​

When you open UnDercontrol, the frontend establishes an SSE connection to the backend. Your session is registered in a per-user connection hub — a structure that tracks every active connection for your account across tabs, devices, and the Electron desktop app. When something changes (a task is updated, an expense is logged, a file is renamed), the backend emits an event onto an internal async event bus. That event fans out to every connection registered under your user ID.

This means if you log an expense on your phone, your browser tab sees it within milliseconds. No polling, no manual refresh.

The connection lifecycle is managed deliberately. Connections are kept alive for up to 30 minutes, after which they cycle and reconnect. This prevents resource leaks on long-running instances and plays nicely with load balancers and reverse proxies that have their own timeout rules. If a connection drops for any reason — network hiccup, sleep/wake cycle, proxy timeout — the client reconnects automatically using exponential backoff. It starts with a short delay and increases gradually, so a briefly offline device does not hammer your server the moment it comes back online.

Smart Cache Updates on the Client​

Getting an event is one thing. Knowing what to do with it is another. UnDercontrol does not blindly refetch the entire dataset when an SSE event arrives. Instead, the frontend applies differential cache updates: it looks at what changed, finds the relevant entry in the local Zustand store, and patches only that record.

For example, if a task's status changes from "in progress" to "done," the event carries just that task's updated state. The client merges it into the existing cache. The list re-renders with the new status. Everything else stays untouched.

This keeps the UI fast and prevents the jarring full-reload effect you see in apps that refetch aggressively.

Optimistic UI and Server Reconciliation​

SSE works alongside UnDercontrol's optimistic update model. When you make a change locally, the UI updates immediately — no spinner, no waiting. The write goes to the server in the background. If it succeeds, the server emits an SSE event that propagates to your other clients. If it fails, the local state reverts and you see an error.

The result is that your primary device feels instant, while your secondary devices stay consistent. The server is the source of truth, and SSE is the mechanism that keeps everyone aligned with it.

Practical Benefits You Will Notice​

Open the same UnDercontrol instance in two browser tabs. Make a change in one. Watch it appear in the other without touching anything.

This is particularly useful when you have a budget overview open on one screen and you are logging transactions on another.

The Electron desktop app participates in the same sync. Changes made through the CLI or the Chrome extension propagate back through SSE to whatever else you have open. The whole multi-platform story depends on this layer working reliably.

Try It Yourself​

All of this runs on your own hardware. There is no cloud dependency, no third-party sync service, and no data leaving your control. The SSE endpoint is part of the standard UnDercontrol backend.

If you are not running UnDercontrol yet, the self-deployment guide covers getting started with Docker in a few minutes. If you are already running an instance, the sync is already active — just open a second tab and see for yourself.

Check the documentation for deployment instructions and configuration options.

kubectl-style Commands, Because It Works​

The CLI uses the same verb-resource pattern that made kubectl feel intuitive to so many engineers. You get, describe, apply, and delete resources. No new mental model required.

# List all tasks
ud get task

# Show full details on a task (short ID prefix supported)
ud describe task 3de9f82b

# Create or update from a markdown file
ud apply -f task.md

# Delete a task
ud delete task abc123

The apply command deserves a highlight. Your task is a markdown file with YAML frontmatter. If the file has an id field, it updates the existing task. No id? It creates a new one. This makes bulk updates, scripted workflows, and version-controlled task definitions straightforward.

echo '---
title: Write release notes
status: in-progress
tags:
  - release
deadline: 2026-04-10
---

Draft the changelog and update the docs site.' | ud apply -f -

Query Syntax That Actually Filters​

ud task query gives you a SQL-like filter language over your tasks. It is useful when you have enough tasks that "scroll through the list" stops being a real strategy.

# Tasks with a deadline this week
ud task query "deadline BETWEEN 'today' AND '+7d'"

# Active tasks tagged urgent
ud task query "(status = 'todo' OR status = 'in-progress') AND tags = 'urgent'"

# Title search
ud task query "title ILIKE '%api%'"

If you would rather not think about syntax at all, ud task nlquery accepts plain English and translates it via AI:

ud task nlquery "show me overdue tasks"
ud task nlquery "tasks tagged with work that are not done"

Both commands accept --sort, --order, and --limit flags for pagination and ordering, so they compose cleanly into scripts or shell aliases.

Notes as a Progress Log​

Every task supports notes — short freeform entries that act as a running log. This is useful for tracking what you actually did, not just the end state.

ud task note add 3de9f82b "Finished the backend changes, opening PR now"
ud task note ls 3de9f82b

Notes also make the CLI a natural fit for AI agent workflows. An agent can create a task from a plan file, append progress notes at each step, and mark the task done — all without touching a browser. The human side of the team sees the full history in the UnDercontrol web UI or desktop app. It is a low-ceremony handoff that actually works in practice.

Interactive TUI for When You Want a Visual​

Running ud with no arguments opens the terminal UI — a keyboard-driven kanban-style interface with vim bindings.

The file picker is a nice touch. Press f, fuzzy-search a markdown file in your current directory, and it becomes a task — first line is the title, the rest becomes the description. Useful when you keep notes in a project repo and want them tracked.

Multi-Context for Multiple Servers​

If you self-host UnDercontrol across multiple environments — personal, work, a staging instance — the context system handles it the same way kubectl does.

ud config set-context work --api-url https://ud.company.com
ud login --context work

# Use a different context for a single command
UD_CONTEXT=personal ud get task

Config lives in ~/.config/ud/config.yaml. You can also drive the CLI entirely through environment variables (UD_API_URL, UD_API_KEY, UD_TOKEN), which makes it usable in CI pipelines without touching config files.

Getting Started​

Install via npm, Homebrew, or a single curl command:

npm install -g @oatnil/ud
# or
brew install oatnil-top/ud/ud
# or
curl -fsSL https://get.oatnil.com/ud | bash

Then point it at your UnDercontrol instance:

ud login

The full command reference — including file attachment, multi-context auth, and advanced query syntax — is in the CLI Reference docs. If you are not running UnDercontrol yet, the self-hosting guide covers getting a server up with Docker in a few minutes.

What a Context Is​

A context in ud is a named configuration that bundles an API endpoint, credentials (either a session token from interactive login or a static API key), and a display username. Contexts live in ~/.config/ud/config.yaml — nothing is sent anywhere.

A typical context list looks like this:

$ ud config get-contexts
CURRENT  NAME      API URL                           USER
*        personal  https://ud.home.example.com       me@example.com
         work      https://ud.corp.example.com       me@corp.com
         local     http://localhost:4000              admin@oatnil.com

The asterisk marks the active context. Every ud command uses that context unless you override it.

Setting Up Your First Context​

The fastest way to create a context is through login. The -n flag names the context in one step:

# Login and create a named context
ud login --api-url https://ud.home.example.com -n personal

# Add another for work
ud login --api-url https://ud.corp.example.com -n work

This prompts for your credentials, authenticates, and saves the token under the given context name. If you need a context for CI/CD or headless environments where interactive login isn't practical, use config set-context with an API key:

ud config set-context ci --api-url https://ud.corp.example.com --api-key ak_xxxxx

Generate API keys from the UnDercontrol web interface under Settings. No browser prompt needed at runtime.

Switching Contexts​

To switch your active context:

ud config use-context work

That's it. Your next ud get task or ud describe task hits the work server with work credentials. Switch back just as easily:

ud config use-context personal

If you're in the TUI, type :ctx in command mode to open an interactive context picker — arrow keys to navigate, Enter to confirm. Same muscle memory as kubectx.

One-off Overrides​

Sometimes you want to target a specific instance for a single command without permanently switching. The --context flag and environment variables handle this:

# Use a named context for one command
ud --context work get task

# Or via environment variable
UD_CONTEXT=work ud get task

# Point at an arbitrary endpoint without a named context
UD_API_URL=http://localhost:4000 UD_API_KEY=dev-key ud get task

The priority order is: --context flag > UD_CONTEXT env var > current-context in config file. This makes scripts explicit about which instance they target, regardless of whatever context happens to be active on the machine.

Independent Auth Per Context​

Each context maintains its own authentication state. Logging out of one context doesn't affect others. If your work session token expires, re-login just that context:

ud login --context work

Your personal and local contexts remain untouched.

Inspecting Your Setup​

# Show which context is active
ud config current-context

# List all contexts
ud config get-contexts

# View the full config (tokens are masked)
ud config view

Housekeeping​

# Rename a context
ud config rename-context old-name new-name

# Delete a context you no longer need
ud config delete-context staging

If you delete the currently active context, ud automatically switches to the first remaining one.

Why This Matters for Self-Hosted Users​

UnDercontrol is built around the premise that your data belongs to you. Running your own instance is a first-class workflow. The context system reflects that — it assumes you might run multiple instances, want to move between them without friction, and need automation without compromising security.

Whether you're managing a personal instance, a family server, and a work deployment, or simply running local dev alongside production, contexts give you a clean mental model and a consistent CLI interface across all of them.

Get Started​

Install the ud CLI via Homebrew (brew install oatnil/ud/ud) or grab a binary from the releases page. Set up your first context:

ud login --api-url https://your-instance.example.com -n myserver

Full documentation: CLI Authentication & Contexts.

This post covers the query system built into UnDercontrol: a SQL-like syntax that works across the web UI, the CLI, custom views, kanban boards, and saved queries. Once it clicks, you will use it constantly.

The Query Syntax​

The syntax is deliberately close to SQL WHERE clauses. If you have ever written a database query, it will feel familiar immediately. If you have not, the basics take about five minutes to pick up.

A simple query looks like this:

status = 'todo' AND deadline <= 'today'

That finds every task that is still todo and due today or earlier — in other words, overdue todo items.

You can build on that with tags, text search, date ranges, and custom fields:

(deadline <= 'today' OR tags = 'urgent') AND status != 'done' AND status != 'archived'

This is a reliable "needs attention now" query. Pin it as a saved query (more on that below) and you have a one-click urgent task list.

Datetime Expressions​

One of the more practical parts of the syntax is the relative date support. Instead of hardcoding dates, you write things like '-7d', '+1w', or just 'today'.

-- Tasks created in the last week
created_at >= '-7d'

-- Due within the next month
deadline BETWEEN 'today' AND '+1m'

-- Updated today
updated_at >= 'today'

The supported units are days (d), weeks (w), months (m), and years (y), with + for future and - for past. Standard ISO 8601 dates like 2025-06-01 also work when you need a fixed date.

Text Search and Custom Fields​

Text search uses LIKE (case-sensitive) and ILIKE (case-insensitive) with % as a wildcard:

title ILIKE '%api%'

For custom fields, prefix with cf.:

cf.priority > 3 AND cf.department = 'engineering'

Custom fields support the full range of comparison operators depending on their type — numbers, text, selects, checkboxes, and user references all work.

Natural Language Queries​

Writing queries manually is fast once you know the syntax. But if you would rather just describe what you want, the AI integration handles the translation.

In the web UI, open the AI Chat panel on the task page and type something like "show me overdue tasks that have the work tag". The AI generates the structured query and runs it.

From the CLI, use ud task nlquery:

ud task nlquery "tasks I need to finish this week"
ud task nlquery "high priority engineering items with no deadline"

The nl alias also works if you want to save a few keystrokes. This requires an AI provider to be configured, but once it is set up it handles surprisingly natural phrasing.

Saved Queries​

This is where the query system becomes genuinely useful day-to-day. Saved Queries let you name and store any query, then run it with a single click from the sidebar.

A few worth setting up immediately:

You can pin queries to keep your most-used ones at the top, reorder them by drag and drop, and edit them at any time. When you click a saved query, results expand inline — no navigation required.

Using Queries in the CLI​

The CLI supports the same query syntax through ud task query:

ud task query "status = 'todo'" --sort deadline --order asc
ud task query "(status = 'todo' OR status = 'in-progress') AND tags = 'work'"

Flags for pagination (--page, --limit) and sorting (--sort, --order) are available. This makes it straightforward to pipe results into other tools or use queries inside shell scripts.

Getting Started​

The full query syntax reference is in the Query Syntax documentation, including every operator, all datetime expression formats, and a full set of practical examples to copy and adapt.

If you are not running UnDercontrol yet, the self-hosting guide covers deployment with Docker. Your data stays on your own infrastructure — that is the whole point.

Here is how the resource management system works in practice.

Upload the Way You Actually Work​

Getting files into UnDercontrol should not require a trip through a file picker every time. There are three main ways to upload:

Drag and drop — open the Resources page or an attachment panel on a task or expense, then drag a file in. Works for single files and batches.

Paste from clipboard — press Ctrl+V and the file in your clipboard uploads immediately. This is particularly useful for screenshots. Take a screenshot of a receipt or a bug in a UI, switch to UnDercontrol, paste. No saving to disk first.

CLI upload — if you live in the terminal, the ud CLI handles uploads directly:

ud upload resource ./receipt.png --entity-type expense --entity-id exp-456

This is useful for scripted workflows, like automatically attaching exported reports to a monthly budget review task.

Attach Once, Reference Everywhere​

A single resource can be linked to multiple items. If you have a contract PDF that is relevant to both a budget and a task, you attach it to both — no duplicates, no hunting through folders. When the task gets marked done, you can unlink the file from it while keeping it attached to the budget.

The inspector panel shows you exactly where a file is attached, so you never lose track of which items reference it.

Find What You Need​

The Resources page gives you a full overview of uploaded files with filtering built in. You can narrow down by file type, by which entity type the file is attached to (tasks, expenses, budgets, accounts), or by a date range. For images, the gallery view shows thumbnails so you can visually scan a set of receipts or screenshots without opening each one.

The inspector also surfaces EXIF metadata for photos — useful if you need to confirm when a photo was taken or where.

Storage: Local or S3​

Because UnDercontrol is self-hosted, you control where your files are stored. The default is local disk storage, which works fine for personal use on a home server or VPS. For larger setups or remote access, you can configure S3-compatible object storage — AWS S3, Backblaze B2, MinIO, whatever you already have.

The key point: your files do not flow through a third-party service. They go from your browser to your server.

Storage limits are configurable. Regular users get 1 GB and a 10 MB per-file cap by default. Admins can operate without limits.

Drawio Diagrams, In-App​

If your workflow involves system diagrams, flow charts, or architecture sketches, UnDercontrol includes built-in drawio support. You can create and edit diagrams directly in the app. No export-to-PNG, no switching to a separate tool and re-uploading. The diagram file lives as a resource attached to whatever task or note it belongs to.

AI on Images​

For receipts and document scans, the AI integration is worth knowing about. You can open an image resource and ask the AI to extract information from it — line items from a receipt, text from a scanned form. This feeds naturally into the expense tracking workflow: photograph a receipt, attach it to an expense, and let the AI pull out the amount and merchant name.

What This Looks Like Day-to-Day​

A practical example: you are tracking a freelance project. There is a task for "Review client contract." You attach the contract PDF to that task. Later, you log an expense for software you purchased for the project. You attach the invoice to the expense. Both files show up in the Resources page, filtered by entity type if you want to see only expense attachments, or together if you want a full file audit for the project.

Everything is in one place. No external file hosting, no email threads to dig through.

Get Started​

If you are already running UnDercontrol, the Resources page is available in the main navigation. If you are evaluating whether to self-host, the deployment guide covers setting up your instance including storage configuration.

The Resource Management documentation has the full reference for CLI commands, storage configuration, and entity attachment options.

UnDercontrol was built from the start to avoid that situation entirely. It is self-hosted, which means you run it on infrastructure you control, and your data lives wherever you put it.

Deploy in Minutes with Docker Compose​

For most people, Docker Compose is the fastest path to a running instance. A single docker-compose.yml file pulls the backend and frontend images, wires them together, and has UnDercontrol running on your server or local machine in a few minutes.

A minimal setup looks roughly like this: a backend service with your data directory mounted as a volume, a frontend service pointing at it, and an optional reverse proxy like Caddy or Nginx in front. That is genuinely all there is to it for a single-user or small household deployment. No managed cloud accounts, no API keys to a third-party service, no data leaving your network.

The Docker image is designed to be small and predictable. It does not phone home, it does not require an internet connection after the initial pull, and it stores everything in the paths you configure.

Kubernetes for Teams and Power Users​

If you are running a homelab with Kubernetes, or you want the kind of reliability that comes with proper orchestration, UnDercontrol ships with Kubernetes manifests as well. You get standard Deployments and Services, PersistentVolumeClaims for your data, and ConfigMaps for environment-specific settings.

This is particularly useful if you are deploying UnDercontrol for a small team — a family, a group of friends, a small company — where you want proper resource limits, rolling updates, and the ability to scale the backend independently if needed. Kubernetes also makes it straightforward to add ingress rules, TLS termination, and namespace-level isolation.

SQLite or PostgreSQL — Pick What Fits​

One of the practical decisions UnDercontrol makes easy is choosing your database. For a single user or a small number of users, SQLite is the default and it works extremely well. There is no database server to manage, no connection pooling to configure, and backups are as simple as copying a file. SQLite is surprisingly capable under these conditions, and it keeps the operational overhead close to zero.

When you need more — concurrent users, larger datasets, integration with existing database infrastructure — switching to PostgreSQL is a matter of changing your environment variables and running migrations. The schema is identical across both backends. You do not have to redesign anything; you just point the application at your Postgres instance and it works.

This flexibility matters because your needs change over time. Starting with SQLite and migrating later is a supported path, not an afterthought.

What Full Data Ownership Actually Means​

Self-hosting means your tasks, your financial records, your uploaded files, and your AI conversation history all live on storage you control. If you want to move to a different server, you copy your data directory and update your deployment. If you want to back up everything, you back up that directory. If you decide to stop using UnDercontrol entirely, your data is still there, in formats you can read.

There is no account to delete, no support ticket to file, no waiting period. The data is yours because it was always on your machine.

This also means you control who has access. Running UnDercontrol on a private network or behind a VPN means your finance data never touches the public internet unless you explicitly route it there. For people who track detailed budgets or sensitive personal information, that is not a small thing.

No Vendor Lock-in by Design​

The backend API is documented and open. The CLI uses kubectl-style commands and works against the same API the web app uses. You can script against it, integrate it with other tools, or build your own clients. The task and note formats are designed to be portable.

The goal was always to build something that earns your continued use because it is genuinely useful — not because migrating away is too painful to bother with.

Get Started​

The deployment guide covers Docker Compose setup, Kubernetes manifests, database configuration, and backup strategies in detail. If you have a server or a spare machine running, you can have a working instance today.

Check out the self-hosting documentation to get started, or open an issue on GitHub if something in the setup does not work the way you expect.

UnDercontrol's AI assistant is built to eliminate that friction. Here is how it actually works in practice.

Snap a Receipt, Skip the Form​

The most immediately useful AI feature is receipt scanning. When you create a new expense, you can upload a photo — drag and drop, paste from clipboard, or select a file. The AI reads the image and extracts the amount, currency, merchant name, date, and a suggested category.

It handles crumpled receipts, tilted angles, and different receipt formats reasonably well. The key practical tip: good lighting matters more than perfect alignment. A clear photo in decent light will almost always parse correctly. A blurry photo taken in a dim restaurant probably will not.

You can also batch-upload multiple receipts at once, which is useful after a work trip or a week where you let things pile up.

Text Input for Quick Logging​

Not every expense comes with a receipt. For those, you can just describe it in plain English:

• "Lunch at the noodle place, 18 dollars"
• "Uber home from the airport, 34 EUR"
• "Monthly Figma subscription 15 USD"

The AI parses the description into a structured expense with the right fields filled in. It is faster than tapping through a form, especially on mobile.

The same pattern works for tasks. Instead of filling out a task form, you describe what needs to happen:

• "Follow up with the accountant about Q1 taxes"
• "Buy a birthday gift for Sarah before Friday"
• "Research self-hosted backup solutions"

UnDercontrol creates a structured task from the description, including a title, any relevant tags it can infer, and a description. You review it, adjust anything that looks off, and save.

Natural Language Queries​

Once you have tasks and expenses in the system, you can ask questions about them in plain language. Things like "show me overdue tasks" or "what is due this week" get translated into a query and return the matching results. It is not magic — it works best with straightforward questions — but it removes the need to remember UnDercontrol's query syntax for everyday lookups.

Apple Shortcuts Integration​

On iOS and macOS, UnDercontrol provides Apple Shortcuts that wire the AI features into the system share sheet and shortcut automation. The practical upside is one-tap capture from anywhere on your device.

The most useful shortcut: snap a photo with your camera, run the shortcut, and the receipt gets logged as an expense without ever opening the app. You can also share text — a copied email snippet, a message, a note — and have a task created from it directly.

The shortcuts are available to download from the Subscribe/Download page in your UnDercontrol instance.

Bring Your Own AI Provider​

UnDercontrol does not lock you into one AI backend. You can connect your own API key from OpenAI, Anthropic, or any OpenAI-compatible service. There is also support for local models via Ollama or LM Studio if you want everything running on your own hardware with no external API calls at all.

Setup is straightforward: go to Profile settings, find the AI Providers section, add your provider and API key, pick a model, and test the connection. You can add multiple providers and prioritize them. The first working provider in your list is what gets used.

If you are running a shared UnDercontrol instance, an administrator can also configure system-level providers that are available to all users — useful for a family server or a small team.

What to Keep in Mind​

AI extraction is good but not perfect. Always glance at the parsed result before saving, especially the amount and date fields. A receipt where the total is visually close to a subtotal line can confuse the parser. Two seconds of review is faster than hunting down a mis-logged expense later.

For text input, more specific descriptions give better results. "Coffee" is harder to categorize than "coffee at the airport before the flight, 6.50 USD."

Getting Started​

If you are already running UnDercontrol, head to your Profile settings and add an AI provider. Then try uploading a receipt the next time you log an expense — the difference in workflow is noticeable immediately.

If you have not set up UnDercontrol yet, the self-hosting guide covers everything from Docker deployment to configuration: UnDercontrol Documentation.

Here's a practical look at how budget tracking works in UnDercontrol.

Creating a Budget That Reflects Reality​

Setting up a budget in UnDercontrol starts with the basics: a name, an initial amount, a start date, and a recurrence frequency. Weekly, monthly, quarterly, or yearly — pick whatever matches how you actually think about money.

But the real power comes from budget plans. Instead of locking you into a single fixed amount, UnDercontrol lets you add new plans over time. Say you start the year with a $500/month grocery budget, then prices go up and you need to revise it to $650 in March. You add a new plan with the updated amount. The system handles the math — calculating totals based on which plan was active during which periods — so your historical data stays accurate and your current view is always up to date.

One-time adjustments fill in the gaps that recurring plans can't cover. Got an unexpected refund? A bonus allocation from a project? A correction to fix a data entry mistake? Each adjustment records an amount, a date, and an optional reason. Future you will appreciate those reasons when reconciling months later.

Logging Expenses and Linking Them to Budgets​

Expenses in UnDercontrol are first-class records. When you log an expense, you can link it to a specific budget. That link is what powers the "budget vs. actual" view — the expense amount rolls up into the budget's spent total, and it appears in that budget's ledger.

This design means you can also have expenses that aren't tied to any budget, which is intentional. Not every transaction needs to be categorized immediately. You can log it, come back later, and link it when it makes sense.

The budget detail page brings everything together: a hero section showing total allocated, total spent, and remaining balance at a glance, plus a spending trend chart that plots your actual spend against the budget line over 7, 30, or 90 days. If you're running a monthly grocery budget and the chart shows you've crossed the allocation line by day 22, that's a clear signal — no mental math required.

Multi-Account Support and the Full Picture​

UnDercontrol's account system lets you track money across multiple sources — checking, savings, a separate business account, whatever your setup looks like. Budget accounts contribute to your overall available balance, so when you're planning a new budget, you're working with real numbers rather than guesswork.

This becomes especially useful when you're managing finances for a small team or household. The collaboration system lets you share budgets with other users, so multiple people can log expenses against the same budget and see the same real-time totals. No more emailing spreadsheets back and forth or manually reconciling two separate tracking systems.

Staying on Top of Spending Without the Overhead​

The budget list page is designed to give you a quick read on everything at once. Progress bars, spent and remaining amounts, and a summary sidebar with aggregated totals across all budgets. Search to find specific budgets quickly. A "Show hidden" toggle for budgets you want to archive without deleting.

Privacy mode deserves a mention: toggle it to hide all monetary amounts across the interface. Useful when you're screen sharing during a meeting and don't need to explain your personal grocery budget to coworkers.

For reporting and data portability, UnDercontrol supports data export so you can pull your expense history out in a structured format. Since you're self-hosting, you also have direct access to the underlying database if you need to run your own queries or pipe data into another tool.

Self-Hosted, Your Rules​

Everything described here runs on your own server. Your financial data doesn't pass through anyone else's infrastructure. You control the backups, the access, and the retention policy. For anyone who's ever felt uncomfortable typing their bank transactions into a third-party app, that matters.

If you want to get started, the self-deployment guide walks through setting up UnDercontrol with Docker. The budget documentation covers every feature in detail, including how budget totals are calculated and how to use adjustments effectively.

Set up your first budget, link a few expenses, and check back in a week. The spending trend chart will tell you more than any spreadsheet ever did.

The Board is a View, Not a Silo​

This is the part worth understanding before anything else. In UnderControl, a kanban board is a visual layer on top of your task system. When you drag a card from "Todo" to "In Progress," you are not just moving a card on a board — you are updating the task's status. That change shows up immediately in your task list, your CLI queries, everywhere. There is no synchronization problem because there is only one source of truth.

This means you can switch between kanban and list views freely without worrying about things getting out of sync.

Getting Started: The All Tasks Board​

Every account comes with a built-in "All Tasks" board. Open it and you will see all your tasks organized across six columns: Todo, In Progress, Pending, Stale, Done, and Archived. This board cannot be deleted and it always appears first.

It is a good place to start. Drag a task from Todo to In Progress, and watch the status update instantly. That is the basic loop — visual placement drives task state, not the other way around.

Custom Boards with Query-Based Columns​

Where things get interesting is when you create your own boards. Each column is defined by a filter condition — essentially a query that determines which tasks belong there. A "Blocked" column might filter for tasks tagged blocked. A "Due This Week" column could filter on due date. The column is not just a label; it is a live query.

When you configure column actions, moving a card becomes a trigger. Drag a task into the "Done" column and it gets marked done automatically. Move something into a "Needs Review" column and it can be tagged and assigned in one gesture. You define what dragging into a column means, and the board handles the bookkeeping.

This is genuinely useful for multi-step workflows. If your process is something like Draft -> Review -> Ready to Ship -> Done, you can model that exactly — with each column transition doing the right thing to the underlying task data.

Private and Shared Boards​

Private boards are scoped to you. You can create as many as you need — one for a side project, one for your weekly planning, one for a home renovation. They all pull from your full task pool, filtered through whatever columns you configure.

Shared boards work differently. When you share a board with a group, the board only shows tasks that belong to that group. Everyone in the group can see the board and move cards around based on their permissions. It is a clean model: the board's scope is the group, and access is controlled through group membership.

This makes shared boards practical for small teams. A sprint board for a two- or three-person team, where everyone can see what is in progress and what is blocked, is easy to set up and does not require any additional tooling.

A Few Workflow Patterns Worth Trying​

If you are not sure how to structure a board, here are a few approaches that work well:

A status-based board mirrors the default setup — Todo, In Progress, Done. Simple, low-overhead, good for solo work.

A time-based board uses columns like Backlog, This Week, Today, and Done. The filter conditions look at due dates or custom fields rather than status. Dragging a task into "Today" can update a priority field automatically.

A project board with shared access uses the group feature to scope tasks to a specific project. Columns map to your team's actual workflow stages, and everyone operates from the same board.

Everything Stays Connected​

Because boards are built on top of the same task and tag system as the rest of UnderControl, they compose naturally with other features. Tags you use in task filters work as column conditions. Custom fields you create for a project can drive column membership and be updated by column actions. The board is not a separate module — it is the task system made visual.

If you want to see how this fits into the broader setup, the Kanban Boards documentation covers column configuration, automatic actions, and sharing in detail. And if you are not running UnderControl yet, the self-hosting guide will get you up and running in under an hour — your data stays on your infrastructure, always.

Here's a practical walkthrough of how the task system works.

Six Statuses That Actually Mean Something​

Tasks in UnderControl move through six statuses: Todo, In Progress, Pending, Done, Stale, and Archived.

The distinction between Pending and Stale is one I find genuinely useful. Pending means you're deliberately waiting — on a reply, a dependency, a decision. Stale means the task just hasn't been touched in a while. That difference matters when you're doing a weekly review and trying to figure out what to act on versus what to clean up.

Pick the View That Matches Your Mental Model​

Different work calls for different views. UnderControl gives you seven:

• List — The default. Fast, filterable, keyboard-friendly.
• Kanban — Drag cards between status columns. Good for sprint-style work.
• Calendar — Tasks plotted by deadline. Useful before a busy week.
• Tree — Hierarchical view of parent and child tasks. Great for projects with nested sub-tasks.
• Graph — A node-link diagram of all your bidirectional task relationships. Looks cool, but also genuinely useful for spotting how things connect.
• Mindmap — Freeform brainstorming layout.
• Trash — Review and restore deleted tasks.

Switching between views doesn't change your data — it's the same tasks, just rendered differently. The Graph view in particular is worth trying if you use linked tasks heavily.

Bidirectional Linking​

You can link any two tasks together, and the connection is bidirectional — follow it from either side. Over time, this turns your task list into something closer to a knowledge graph. The Graph view is where this becomes visible: nodes are tasks, edges are links, and you can see clusters form around related work.

Derived tasks (parent-child relationships) work differently. When you create a task from an existing one, the child inherits context from the parent and links back to it automatically. This is the right pattern for breaking down a large project into concrete steps.

Markdown Notes with Edit History​

Every task has a notes section. Notes support full markdown — headers, code blocks, lists, links. More importantly, every note keeps a full edit history. If you wrote something, changed your mind, and want to go back, you can revert to any previous version.

I use notes for things like decision logs, blockers, and meeting summaries attached to a task. It keeps everything in one place instead of scattered across documents and chat threads.

Filtering and Queries​

The quick filters cover the common cases: filter by status, tags, or deadline range (overdue, today, this week, and so on). For more specific needs, there's a structured query language:

status = 'pending' AND tag:work = 'true'

If you don't want to write the query yourself, the AI assistant accepts plain English — something like "show me overdue tasks tagged with client work" — and translates it into a filter.

File Attachments and Sharing​

Attach any file to a task — images, PDFs, diagrams, exported reports. The attachments live on your server, under your control.

For sharing, you can generate a public link to a specific task with an optional expiration date. Or share with a group and set whether they get read or read-write access.

The CLI Is a First-Class Interface​

If you work in a terminal, ud gives you the full task API from the command line:

ud task list
ud task create "Review Q2 metrics"
ud task done <id>
ud task query "status = 'todo' AND deadline < '2026-05-01'"
ud task apply -f task.md

The apply command is particularly useful — you can write a task in a markdown file and push it to UnderControl, which fits nicely into scripting and automation workflows. The CLI follows kubectl-style conventions, so if you spend time in Kubernetes or similar tools, the patterns feel familiar.

Recurring Tasks and Check-ins​

For repeating work, recurring tasks generate new task instances on a schedule — daily standups, weekly reviews, monthly reports. You can use presets or write a custom CRON expression.

Check-ins are a lighter-weight alternative for habit tracking: each check-in increments a counter and records a timestamp, giving you a simple log of consistency without the overhead of a full task lifecycle.

Try It Yourself​

All of this runs on your own infrastructure. No data leaves your server, no subscriptions, no vendor lock-in.

The full task management documentation is at undercontrol.dev/docs/tasks, and the self-hosting guide covers deployment with Docker or the prebuilt binaries. If you run into anything, the GitHub repo is the right place to file issues or ask questions.