index

Forge

An AI harness for your filesystem. Obsidian-pilled, local-disk-pilled. A Mac desktop app that opens to a blinking cursor — no panels, no file tree, no menus. You type what you want. The agent does it, on your files, with your collaborators, and renders only the UI it needs.

The shift

Obsidian = UI shell + plugins that manipulate the UI. The user composes the workspace by installing panels.

Cursor / Claude Code = a harness around an AI model that turns a codebase into a working assistant. The user gives intent; the agent operates on files; UI is rendered just-in-time (diff views, inline edits, agent panels).

Forge = the Cursor/Claude Code idea, but for the rest of your work — invoices, contracts, customer comms, taxes, scheduling, planning. An IDE for productivity, where the substrate is your filesystem (markdown + attachments) and the labor is an agent.

The opening screen is a blinking cursor. Everything else is generated.

Primitives

Primitive	What it is	Replaces (Obsidian)
Project	One repo, one purpose, plentiful. ~/forge/tax-2026/, ~/forge/acme-co/	Vault
Workspace	All projects under one root (~/forge/)	—
Agent	The harness. Reads intent, calls skills/connectors, renders JIT UI, writes files, makes commits.	The app shell + every panel
Skill	Bundled prompt + code + knowledge. Project- or workspace-scoped. Agent-composable.	Plugin
Connector	MCP server bridging an external system (QuickBooks, Stripe, Gmail, Drive, Slack)	Plugin’s bespoke HTTP code, standardized
Collaborator	Human or agent. Both are first-class participants in the repo’s commit graph.	— (Obsidian is single-player)

Architecture

flowchart TB
    subgraph App["Mac desktop app (Tauri shell)"]
        Canvas["Blank canvas
        (blinking cursor)"]

        subgraph Harness["Forge harness"]
            Agent["Agent runtime"]
            JIT["JIT UI runtime
            (A2UI + Tambo)"]
            Skills["Skills"]
            MCP["Connectors (MCP)"]
        end

        Canvas <--> Agent
        Agent <--> JIT
        Agent --> Skills
        Agent --> MCP
    end

    subgraph FS["Local filesystem (~/forge/)"]
        P1["tax-2026/"]
        P2["acme-co/"]
        P3["home/"]
    end

    Harness <--> FS
    FS -. git push/pull .-> GH[("GitHub
    1 repo / project")]
    MCP -. MCP .-> Ext[(QuickBooks, Stripe,
    Gmail, Drive...)]
    JIT -. publish .-> Quartz[(Per-project
    Quartz sites)]
    GH -. repo invite .-> Collab([Human or agent
    collaborator])

Core principles

1. Local disk is the source of truth. Every project is a folder of plain markdown + JSON + attachments. No proprietary format. cp -r to leave at any time.
2. GitHub is the sync layer. One repo per project. Free backup, free versioning, free audit trail. Works with any forge (GitLab, Gitea, Forgejo).
3. Projects are plentiful and scoped. A vault holds your whole life; a project holds one thing. Small blast radius for sharing, archiving, deleting.
4. The agent is the UI. No pre-built panels. JIT rendering means the interface matches what you’re doing right now — table, editor, kanban, chat, diff, calendar.
5. Collaborators are first-class. Humans and agents commit alongside each other. Repo activity is the audit log.
6. Skills > plugins. Skills are agent-composable units. The user doesn’t pick which plugin handles “invoice” — the agent does.
7. Publish is native. Quartz baked in. Each project knows its public face and its audience.

Target user

Personal admin + small business (1–10 people). Sole proprietors, freelancers, family offices, neighborhood law firms, indie shops, two-person agencies — operators who:

• Have no CFO, COO, or ops manager
• Currently glue together 6+ SaaS tools (QuickBooks + Notion + Gmail + Stripe + Calendly + Zapier + a personal “ops” doc)
• Care about data privacy (client confidentiality, GDPR)
• Will trade a sprawling tool stack for one assistant that handles it all

Anti-personas:

• Hardcore Obsidian zealots (anti-cloud, anti-AI by ideology — Forge is explicitly AI-first and Git-backed)
• Big enterprise (SSO, SOC 2, procurement — different product, later)
• Developers (different jobs to be done — they have Cursor)

JIT UI runtime

The “agent is the UI” principle needs a real rendering substrate. The landscape as of May 2026:

Framework	What it is	Fit for Forge
A2UI (Google, v0.9, late 2025)	Open standard for agents to declare UI intent against a component catalog. Streaming, resilient parsing, framework-agnostic. Flutter GenUI SDK alongside the spec.	Strong — open protocol, no vendor lock, designed exactly for this.
MCP-UI	Extends MCP with a UIResource interface. Three render paths: inline HTML in sandboxed iframe, external URL, Remote DOM.	Strong, complementary — we already use MCP for connectors. A Stripe connector can emit a payment-review widget natively.
Tambo	React SDK + backend. Register components with Zod schemas; the agent picks one and streams props. MCP-native.	Strong — best developer ergonomics if we’re React-based.
Thesys C1	LLM API endpoint that returns structured UI components directly. OpenAI-compatible.	Vendor-coupled to Thesys’s generation pipeline; rules it out as a foundation.
CopilotKit + AG-UI	Older agentic-UI protocol, now mostly a bridge to A2UI / MCP-UI.	Skip the abstraction layer; go to A2UI directly.
Vercel JSON-Render (March 2026)	JSON-based generative UI for the Vercel AI SDK.	Adjacent; lock-in to Vercel ecosystem.

Stack pick:

• A2UI as the protocol (open, framework-agnostic, Google-backed durability).
• Tambo as the React renderer (ships fastest, MCP-native).
• MCP-UI for connector-emitted UI (a Stripe connector returns a “review payment” widget; Forge renders it inline).
• A small Forge component catalog (table, kanban, editor, diff, calendar, chat, form) that A2UI agents draw from.

Desktop shell

Mac-first. Native-feeling but cross-platform later.

• Tauri 2 (Rust shell, web frontend) — small binary, secure-by-default sandboxing, native file-system + keychain access. The local-first ethos pick.
• Electron — pragmatic fallback if the team is JS-only and wants to move faster at V0.

The shell exists to provide: (1) a native window with the blinking-cursor surface, (2) filesystem access without sandboxing pain, (3) keychain for connector creds, (4) menu-bar / global hotkey to invoke Forge from anywhere, (5) local sub-process management for the agent runtime and MCP servers.

No native UI to design — the shell is a host for the JIT UI runtime.

Skill packaging

Adopt Claude Code’s skill format directly:

~/forge/<project>/.forge/skills/<skill-name>/
  SKILL.md          # frontmatter (name, description, when-to-use) + body
  scripts/          # optional executables
  templates/        # optional templates
  resources/        # optional reference docs

Workspace-scoped skills live in ~/forge/.forge/skills/. Project-scoped skills override workspace ones. Skills are committed to the project repo for portability.

Sync & publish (agentic, not CLI)

• The working tree is canonical. The agent auto-commits and auto-pushes on quiescence; conflicts surface as a JIT diff view the agent helps resolve.
• Publishing is a verb the user speaks, not a command they type. “Publish this to the client portal” → agent renders a preview of what’ll go public, user confirms, agent runs the Quartz build and deploys.
• Each project carries its own publish config (one or more audiences, each mapped to a Cloudflare Pages site). The atelier-publish pattern, internalized.

What Forge is not

• Not a chat sidebar bolted onto Obsidian. That’s Copilot-for-Obsidian. Plugin-shaped.
• Not a Cursor clone. Cursor is a harness for code. Forge is a harness for everything else.
• Not Notion. Notion is cloud-first, blocks-first, single-tenant DB. Forge is files-first, repo-per-project, local.
• Not Logseq or a PKM tool. PKM is for thinking. Forge is for doing — invoices, contracts, customer comms, taxes, scheduling.

Open questions

• Skill format: adopt Claude Code skill format verbatim, or extend?
• Connector auth: per-project credentials, workspace-level key vault, or hybrid? OS keychain integration?
• Agent runtime: local (Ollama / MLX) for privacy-strict users, cloud (Claude / GPT) for capability, or both with a routing policy?
• JIT UI fallback: when the agent wants a UI shape the component catalog doesn’t have, does it (a) compose from primitives, (b) generate ad-hoc HTML via MCP-UI’s iframe path, or (c) decline?
• Mobile: native iOS/Android, PWA, or punt to v2?
• Discoverability of skills: marketplace, npm-style registry, or “install from any Git URL”?