Forem: Oatnil

Access Anywhere — Web, Desktop, CLI, and Beyond

Oatnil — Wed, 29 Apr 2026 01:20:59 +0000

When choosing a productivity tool, you often face a familiar dilemma: web apps are powerful but useless offline, desktop apps feel great but lock your data locally, and CLI tools are developer-friendly but lack a visual interface. The root cause is the absence of a Single Source of Truth — each platform is an island, and your data is scattered across them. UnDercontrol's answer: four form factors, one data source. And that data source is entirely under your control — self-hosted on your own server or stored on your local disk, never passing through any third party. Privacy and security are defined by you.

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

Capability	Web	Desktop	CLI	Extension
Remote API access	✅	✅	✅	✅
Embedded backend	❌	✅ (switchable to remote)	❌	❌
Offline mode	❌	✅	❌	✅
System tray	❌	✅	❌	❌
TUI interface	❌	❌	✅	❌
Background Daemon	❌	✅	❌	❌
Web clipping	❌	❌	❌	✅
Real-time SSE	✅	✅	❌	❌
AI Agent friendly	✅	✅	✅	❌

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.

Rich Markdown in Your Tasks — Code, Diagrams, and More

Oatnil — Tue, 28 Apr 2026 00:52:07 +0000

What Is a Task?

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.