Noktua

What is Noktua?

Noktua is your AI chief of staff as a Mac app. One conversation. One interface. You tell it what you want, it figures out what to do — delegates to specialised agents, controls your desktop, browses the web, manages your files — and reports back.

It's built on top of openwork (the Electron desktop agent framework) and deepagents (LangChain's deep agent runtime) — then heavily extended with Xena-style orchestration patterns: YAML registries, subagent spawning, browser automation, middleware resilience, and the same tool routing architecture.

Why does this exist?

Every AI desktop app is basically a chat wrapper around one model. You talk, it replies, you're still doing all the work. The model can't actually do things on your computer, can't run tasks in the background, can't follow up on its own, can't coordinate multiple jobs at once.

Noktua is different because:

• You talk to one orchestrator — Noktua itself. It decides which agents to delegate to, what tools to use, and when to come back to you.
• Subagents run in the background — up to 4 concurrent agents, each streaming in their own tab. You can watch or ignore them.
• It controls your Mac — screenshots, clipboard, file system, app control. No OAuth dance required.
• It browses the web for you — real browser automation via Browser Use, streamed live so you can see what it's doing.
• It's local-first — your data lives in ~/.openwork/. Your API keys. Your machine. No cloud backend.
• Any model, any provider — Anthropic, OpenAI, Google, Cerebras, Ollama. Swap models mid-conversation.

How It Works

The Conversation Flow

The Middleware Stack

Noktua's runtime isn't just "call an LLM and hope." It's a carefully ordered middleware stack that handles everything between your message and the model's response:

createAgentRuntime(threadId, modelId, workspacePath)
│
├─ 1. Model fallback         → same-provider first, then cross-provider
├─ 2. Resilience             → additive backoff (20s→30s→40s), 6 retries / 5 min
├─ 3. Todo list              → persistent task tracking across turns
├─ 4. Filesystem backend     → ls, read, write, edit, glob, grep (LocalSandbox)
├─ 5. Summarization          → model-aware token/message triggers
├─ 6. Prompt caching         → Anthropic cache headers
├─ 7. Tool arg normalizer    → clean up model output quirks
├─ 8. Tool allowlist         → only registered tools pass through
└─ 9. Human-in-the-loop      → interrupt gate on execute

This order matters. Fallback wraps resilience. Resilience wraps filesystem. Summarization compresses before you hit context limits. HITL is the final gate before anything touches your system.

When context overflows, the runtime doesn't crash — it compacts messages and retries once before surfacing an error. When a provider rate-limits you, it backs off with additive delays and a bounded retry budget. When one model fails entirely, it falls through to alternatives automatically.

The Registry System

Everything in Noktua is defined in YAML files, not hardcoded. Three registries compose to create the full capability surface:

version: 2
tools:
  - path: agent.task.spawn
    description: Spawn a background subagent
    required: [name, description, agent_id]
  - path: browser.task.run
    description: Run a browser automation task
    required: [task]

agents:
  - id: email-handler
    name: Email Agent
    model: anthropic:claude-sonnet-4-5-20250929
    skill: communication
    tools: [communication.email.reply, communication.email.send]
  - id: researcher
    name: Research Agent
    model: openai:gpt-4o
    skill: research
    tools: [browser.task.run]

This is the macro.micro.atomic composition pattern: agents (macro) are composed of skills (micro) and tools (atomic). Everything is a file. Everything is swappable.

Progressive Disclosure

Noktua is designed in layers. You only go as deep as you want:

Multi-Provider Intelligence

Noktua isn't locked to one AI provider. Models are fetched dynamically from provider APIs on launch:

Fallback chains are built automatically: same-provider alternatives first, then cross-provider with available keys. Switch models mid-conversation. The thread's checkpoint persists regardless of which model you're talking to.

Local-First by Design

Everything lives on your machine:

No cloud backend. No telemetry. No account required. Bring your own API keys and you're running.

What Makes This Different

The key differences from every other desktop AI app:

• Real subagent orchestration — not just "call the API." Actual background agents with their own threads, streaming, and lifecycle management. Up to 4 running concurrently.
• Browser automation built in — via Browser Use, with live streaming so you can watch the browser work. Not a screenshot. A live session.
• HITL that actually works — interrupt-driven approval for dangerous operations, with the ability to edit commands before they run.
• YAML-first extensibility — no plugin API to learn. Edit a file, restart, done. Tools, skills, and agents are just YAML.
• Provider agnostic — use Claude for reasoning, GPT for research, a local Ollama model for quick tasks. Mix and match per agent.
• Resilience as infrastructure — rate limiting, context overflow, model failures — all handled by middleware, not hope.

Tech Stack

Install

npm install -g openwork
openwork

Or clone and run in development:

git clone https://github.com/nof0xgiven/noktua.git
cd noktua
pnpm install
pnpm dev

References

• LangChain JS — Agent creation and middleware: js.langchain.com
• LangGraph — Stateful agent orchestration: LangGraph docs
• openwork — Electron desktop agent framework (upstream fork): GitHub
• deepagents — LangChain's deep agent runtime: GitHub
• Browser Use — Cloud browser automation: browser-use.com
• Xena — The webhook-first sibling architecture: Xena docs