@knowsuchagency/fulcrum 1.14.1 → 2.0.0

package/README.md

@@ -2,70 +2,48 @@
 
 **Harness Attention. Orchestrate Agents. Leverage Your Time Wisely.**
 
-![Fulcrum Kanban Board](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/tasks-kanban-board.png)
+![Fulcrum Kanban Board with AI Assistant](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/kanban-with-assistant.png)
 
 ## What It Does
 
-Run multiple AI coding agent sessions in parallel across isolated git worktrees. Monitor them all from one screen. Close your laptop—they keep working. Deploy to production when ready. Self-hosted and open source.
-
-Fulcrum supports **Claude Code** and **OpenCode** with per-repository and per-task agent selection.
-
-- **Full Development Lifecycle** — Develop features in isolated git worktrees, then deploy to production with Docker Compose. No context switching, no vendor lock-in.
-- **Parallel Agent Orchestration** — Run multiple AI agent sessions across different tasks and worktrees. See and control all sessions in one parallel view.
-- **Work From Anywhere** — Close your laptop—your agents keep working on your behalf. Pick up where you left off from your phone.
-- **Multi-Agent Support** — Choose between Claude Code and OpenCode. Set a global default, override per-repository, or select per-task.
-- **Open Source & Self-Hosted** — Inspect the code, run it anywhere, own your data. From a $5 VPS to your home lab.
-
-## Key Features
-
-- **Projects** — Unified view combining repositories and app deployments with workspace terminals
-- **App Deployment** — Deploy with Docker Compose, automatic Traefik routing, optional Cloudflare DNS integration
-- **Parallel Agent Orchestration** — Run multiple AI coding agent sessions across different tasks and worktrees
-- **Multi-Agent Support** — Use Claude Code or OpenCode, configurable globally, per-repo, or per-task
-- **Work From Anywhere** — Run on a remote server; agents continue working when you disconnect
-- **Git Worktree Isolation** — Safe experimentation without touching your main branch
-- **Claude Code Plugin** — Skill for task management, automatic status sync, session continuity
-- **MCP Server** — 60+ tools for tasks, projects, apps, and remote execution
-- **Kanban Task Management** — Visual task tracking from planning to done
-- **Task Dependencies** — Define prerequisite tasks; visualize with dependency graph
-- **Task & Project Context** — Attach files, add reference links, set due dates, organize with labels
-- **PR Monitoring** — Track pull requests across repositories
-- **Linear Integration** — Sync task status with Linear tickets
-- **Job Scheduling** — Create and manage systemd/launchd timers from the UI
-- **Cross-Platform** — Desktop app (Mac, Linux) or web application
+Run multiple AI coding agents in parallel across isolated git worktrees. Manage projects with tasks, dependencies, and scheduling. Deploy to production when ready. Work from anywhere—your agents keep running when you close the laptop. Self-hosted and open source.
 
-## Quick Start
+**Five pillars:**
 
-```bash
-npx @knowsuchagency/fulcrum@latest up
-```
+- **Terminal-First Orchestration** — Run Claude Code, OpenCode, or other agents in real terminals. No abstraction layer, no wrapper APIs.
+- **Work From Anywhere** — Run Fulcrum on a remote server. Kick off tasks, close your laptop, check progress from your phone. Agents keep working in the background.
+- **Project Management** — Tasks with dependencies, due dates, labels, and attachments. Visual kanban boards and dependency graphs.
+- **Production Deployment** — Docker Compose with automatic Traefik routing and Cloudflare DNS/tunnels.
+- **MCP-First Architecture** — 60+ tools exposed via Model Context Protocol. Agents discover what they need.
+
+## MCP-First Architecture
 
-That's it! Fulcrum will:
-- Check for required dependencies (bun, dtach, AI agent CLI, uv)
-- Offer to install any that are missing
-- Start the server on http://localhost:7777
-- Show getting started tips
+Everything in Fulcrum is exposed through MCP (Model Context Protocol):
 
-Open http://localhost:7777 in your browser.
+- **60+ MCP tools** for tasks, projects, apps, repos, notifications, and remote execution
+- **Smart tool discovery** — `search_tools` lets agents find relevant tools without loading everything into context
+- **Integrated assistant** — Built-in AI assistant with full context of your tasks, projects, and apps
+- **External agent support** — Connect Claude Desktop, Clawdbot, or any MCP-compatible agent
+- **No context bloat** — Agents discover and use only the tools they need
 
-### Check Your Setup
+Whether you use Fulcrum's built-in assistant or an external agent like Claude Desktop, AI has seamless access to your entire workflow.
+
+## Quick Start
 
 ```bash
-fulcrum doctor
+npx @knowsuchagency/fulcrum@latest up
 ```
 
-Shows the status of all dependencies with versions.
+Fulcrum will check for dependencies (bun, dtach, AI agent CLI), offer to install any that are missing, and start the server on http://localhost:7777.
 
 ### Desktop App
 
-Download the desktop app for a bundled experience:
-
 | Platform | Download |
 |----------|----------|
 | **macOS** (Apple Silicon) | [Download DMG](https://github.com/knowsuchagency/fulcrum/releases/latest/download/Fulcrum-macos-arm64.dmg) |
 | **Linux** | [Download AppImage](https://github.com/knowsuchagency/fulcrum/releases/latest/download/Fulcrum-linux-x64.AppImage) |
 
-The desktop app bundles everything—just install and run. It will start the server, install the Claude Code plugin, and check for updates automatically.
+The desktop app bundles everything—just install and run.
 
 <details>
 <summary>macOS Installation Notes</summary>
@@ -77,7 +55,7 @@ The desktop app bundles everything—just install and run. It will start the ser
 
 </details>
 
-### Install Script (Recommended for Remote Servers)
+### Install Script (Remote Servers)
 
 For remote servers or VPS, use the install script—it auto-installs all dependencies:
 
@@ -85,8 +63,6 @@ For remote servers or VPS, use the install script—it auto-installs all depende
 curl -fsSL https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/install.sh | bash
 ```
 
-This installs bun, dtach, uv, Claude Code, OpenCode, GitHub CLI, Docker, cloudflared, and the fulcrum CLI + Claude Code plugin.
-
 ### Claude Code Plugin
 
 Install the plugin for automatic status sync and task management:
@@ -98,65 +74,66 @@ claude plugin install fulcrum@fulcrum --scope user
 
 ## Features
 
-### Kanban Board
+### Kanban Board & AI Assistant
+
+Track tasks from planning to done. The built-in AI assistant has full context of everything you're tracking—tasks, projects, apps—and can help with planning, documentation, or running MCP tools.
 
-Track tasks from planning to done. Create tasks that automatically spin up isolated git worktrees, and watch their status update in real-time as you work with your AI agents.
+![Kanban Board with AI Assistant](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/kanban-with-assistant.png)
 
-![Kanban Board](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/tasks-kanban-board.png)
+### Parallel Agent Orchestration
 
-### Task Terminals View
+Run multiple AI coding agents simultaneously across different tasks. Each task gets an isolated git worktree. Monitor and interact with all sessions from one screen.
 
-See all your AI agent sessions across every task in a single parallel view. Each task creates an isolated git worktree on-demand, and you can monitor and interact with all sessions simultaneously.
+![Parallel Agent Terminals](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/parallel-agent-terminals.png)
 
-![Task Terminals View](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/terminals-view-with-tests.png)
+### Projects
 
-### App Deployment
+Unified view of repositories and deployments. Link repos, manage tasks, configure default agents, and see active work at a glance.
 
-Deploy applications directly from Fulcrum with Docker Compose. Edit compose files inline, configure environment variables, and manage services with automatic Traefik routing and optional Cloudflare DNS integration.
+![Projects List](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/projects-list.png)
 
-![App Deployment](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/app-deployment-config.png)
+### Project Workspace
 
-### Projects
+Terminal with integrated file browser. Direct access to project files alongside your agent sessions.
 
-Projects unify your code repositories and app deployments into a single entity. Manage workspace terminals, task settings, and deployment configuration from one place.
+![Project Workspace](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/project-workspace.png)
 
-![Projects](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/repositories-view.png)
+### Task Dependencies
 
-### Browser Preview
+Define prerequisite tasks that must complete before others can start. Visualize with an interactive dependency graph.
 
-Preview your app alongside the agent terminal in a split-pane view. Watch changes in real-time as your AI agent iterates on your code.
+![Task Dependency Graph](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/task-dependency-graph.png)
 
-![Browser Preview](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/browser-preview-split-view.png)
+### AI Assistant
+
+Create documents with live preview. Generate charts and visualizations. The assistant uses the same MCP tools available to external agents.
+
+![AI Assistant Editor](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/assistant-editor.png)
 
 ### System Monitoring
 
-Keep an eye on system resources while your agents work. CPU, memory, and disk usage at a glance. The Jobs tab lets you create and manage systemd (Linux) or launchd (macOS) timers.
+Track CPU, memory, and disk usage while your agents work. The Jobs tab manages systemd (Linux) or launchd (macOS) timers.
 
-![System Monitoring](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/monitoring-system-metrics.png)
+![System Monitoring](https://raw.githubusercontent.com/knowsuchagency/fulcrum/main/screenshots/system-monitoring.png)
 
 ## Supported Agents
 
-Fulcrum supports multiple AI coding agents:
-
 | Agent | Description |
 |-------|-------------|
 | **Claude Code** | Anthropic's CLI coding agent with deep MCP integration |
 | **OpenCode** | Open-source coding agent with GPT-4 and other model support |
 
-Configure your default agent globally in settings, override per-repository, or select per-task when creating new tasks.
+Configure your default agent globally, per-repository, or per-task.
 
 ## Claude Code Plugin
 
-The Fulcrum plugin for Claude Code enables seamless integration:
+The Fulcrum plugin enables seamless integration:
 
 - **Automatic Status Sync** — Task moves to "In Review" when Claude stops, "In Progress" when you respond
-- **Session Continuity** — Claude sessions are tied to task IDs
+- **Session Continuity** — Sessions tied to task IDs
 - **MCP Server** — Task management tools available directly to Claude
-- **Fulcrum Skill** — CLI documentation for task management (see `plugins/fulcrum/skills/`)
 - **Slash Commands** — `/review`, `/pr`, `/notify`, `/linear`, `/task-info`
 
-The plugin is automatically installed when Fulcrum starts. To install manually:
-
 ```bash
 claude plugin marketplace add knowsuchagency/fulcrum
 claude plugin install fulcrum@fulcrum --scope user
@@ -164,12 +141,6 @@ claude plugin install fulcrum@fulcrum --scope user
 
 ## OpenCode Integration
 
-The Fulcrum plugin for OpenCode enables seamless integration:
-
-- **Automatic Status Sync** — Task moves to "In Review" when OpenCode stops, "In Progress" when you respond
-- **Session Continuity** — OpenCode sessions are tied to task IDs
-- **MCP Server** — Task management tools available directly to OpenCode
-
 ```bash
 fulcrum opencode install    # Install plugin + MCP server
 fulcrum opencode uninstall  # Remove both
@@ -177,7 +148,7 @@ fulcrum opencode uninstall  # Remove both
 
 ## MCP Tools
 
-Both Claude Code and OpenCode plugins include an MCP server with 60+ tools for task management, project organization, app deployment, and remote execution:
+Both plugins include an MCP server with 60+ tools:
 
 | Category | Description |
 |----------|-------------|
@@ -207,11 +178,9 @@ For Claude Desktop, add to your `claude_desktop_config.json`:
 
 ## Remote Server Setup
 
-Run the backend on a remote server and connect from anywhere. Launch tasks, close your laptop, and your agents keep working. As AI becomes more capable of autonomous work, this becomes essential.
+Run the backend on a remote server and connect from anywhere. Launch tasks, close your laptop, and your agents keep working.
 
-### Desktop App: SSH Port Forwarding (Recommended)
-
-The desktop app connects to `localhost:7777`. Use SSH port forwarding to tunnel to your remote server:
+### SSH Port Forwarding (Recommended)
 
 ```bash
 # Forward local port 7777 to remote server's port 7777
@@ -221,36 +190,24 @@ ssh -L 7777:localhost:7777 your-server
 ssh -fN -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 7777:localhost:7777 your-server
 ```
 
-On the remote server, start Fulcrum:
+On the remote server:
 ```bash
 npx @knowsuchagency/fulcrum@latest up
 ```
 
-The desktop app will connect through the tunnel automatically. This approach is:
-- **Secure** — Backend stays bound to localhost, no exposed ports
-- **Performant** — Direct SSH connection, lower latency than overlay networks
-- **Simple** — No additional configuration needed
-
-For persistent tunnels on macOS, use a launchd agent. See [this guide](https://gist.github.com/knowsuchagency/60656087903cd56d3a9b5d1d5c803186).
+The desktop app connects through the tunnel automatically. This is secure (no exposed ports), performant (direct SSH), and simple (no extra config).
 
-### Browser: Tailscale or Cloudflare Tunnels
+### Browser Access
 
-For browser-only access, you can use Tailscale or Cloudflare Tunnels to expose your server:
-
-1. **On the remote server:**
-   ```bash
-   npx @knowsuchagency/fulcrum@latest up
-   ```
-
-2. **Access via browser** — Open the tunnel URL (e.g., `http://your-server.tailnet.ts.net:7777`)
+For browser-only access, use Tailscale or Cloudflare Tunnels to expose your server.
 
 <details>
 <summary><strong>Configuration</strong></summary>
 
 Settings are stored in `.fulcrum/settings.json`. The fulcrum directory is resolved in this order:
 
-1. `FULCRUM_DIR` environment variable (explicit override)
-2. `.fulcrum` in current working directory (per-worktree isolation)
+1. `FULCRUM_DIR` environment variable
+2. `.fulcrum` in current working directory
 3. `~/.fulcrum` (default)
 
 | Setting | Env Var | Default |
@@ -262,26 +219,22 @@ Settings are stored in `.fulcrum/settings.json`. The fulcrum directory is resolv
 | integrations.githubPat | `GITHUB_PAT` | null |
 | appearance.language | — | null (auto-detect) |
 
-Notification settings (sound, Slack, Discord, Pushover) are configured via the Settings UI or CLI.
-
-Precedence: environment variable → settings.json → default
+Notification settings (sound, Slack, Discord, Pushover) are configured via Settings UI or CLI.
 
 ### Linear Integration
 
-Fulcrum can sync task status with Linear tickets. Configure `linearApiKey` in settings or set `LINEAR_API_KEY`. When a task is linked to a Linear ticket, status changes in Fulcrum automatically update Linear.
+Sync task status with Linear tickets. Configure `linearApiKey` in settings or set `LINEAR_API_KEY`.
 
 </details>
 
 <details>
 <summary><strong>CLI Reference</strong></summary>
 
-The CLI lets AI agents working inside task worktrees query and update task status.
-
 ### Server Management
 
 ```bash
 fulcrum up                        # Start server daemon
-fulcrum up -y                     # Start with auto-install (no prompts)
+fulcrum up -y                     # Start with auto-install
 fulcrum down                      # Stop server
 fulcrum status                    # Check server status
 fulcrum doctor                    # Check all dependencies
@@ -291,14 +244,12 @@ fulcrum mcp                       # Start MCP server (stdio)
 ### Current Task (auto-detected from worktree)
 
 ```bash
-fulcrum current-task info         # Get current task info (default)
+fulcrum current-task info         # Get current task info
 fulcrum current-task review       # Mark as IN_REVIEW
 fulcrum current-task done         # Mark as DONE
 fulcrum current-task cancel       # Mark as CANCELED
-fulcrum current-task pr <url>     # Associate a PR with current task
-fulcrum current-task link <url>   # Add a reference link to the task
-fulcrum current-task link         # List all links
-fulcrum current-task link -r <id> # Remove a link
+fulcrum current-task pr <url>     # Associate a PR
+fulcrum current-task link <url>   # Add a reference link
 ```
 
 ### Agent Integration
@@ -310,31 +261,13 @@ fulcrum opencode install          # Install OpenCode plugin + MCP server
 fulcrum opencode uninstall        # Remove plugin + MCP server
 ```
 
-### Configuration
-
-```bash
-fulcrum config get <key>          # Get a config value
-fulcrum config set <key> <value>  # Set a config value
-```
-
 ### Notifications
 
 ```bash
 fulcrum notifications             # Show notification settings
-fulcrum notifications enable      # Enable notifications
-fulcrum notifications disable     # Disable notifications
-fulcrum notifications test <ch>   # Test a channel
 fulcrum notify <title> [message]  # Send a notification
 ```
 
-### Global Options
-
-```bash
---port=<port>     # Server port (default: 7777)
---url=<url>       # Override full server URL
---pretty          # Pretty-print JSON output
-```
-
 </details>
 
 ## Internationalization

package/bin/fulcrum.js

@@ -1123,9 +1123,10 @@ class FulcrumClient {
     return this.fetch("/api/config/notifications");
   }
   async updateNotifications(updates) {
+    const current = await this.getNotifications();
     return this.fetch("/api/config/notifications", {
       method: "PUT",
-      body: JSON.stringify(updates)
+      body: JSON.stringify({ ...updates, _updatedAt: current._updatedAt })
     });
   }
   async testNotification(channel) {
@@ -43764,6 +43765,24 @@ var init_registry = __esm(() => {
   ];
 });
 
+// shared/date-utils.ts
+function getTodayInTimezone(timezone) {
+  const now = new Date;
+  if (!timezone) {
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+  }
+  const formatter = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  });
+  return formatter.format(now);
+}
+
 // cli/src/mcp/tools.ts
 import { basename as basename2 } from "path";
 function registerTools(server, client) {
@@ -43860,7 +43879,9 @@ function registerTools(server, client) {
         tasks = tasks.filter((t2) => t2.dueDate && t2.dueDate <= dueDateEnd);
       }
       if (overdue) {
-        const today = new Date().toISOString().split("T")[0];
+        const config3 = await client.getConfig("appearance.timezone");
+        const timezone = config3?.value ?? null;
+        const today = getTodayInTimezone(timezone);
         tasks = tasks.filter((t2) => t2.dueDate && t2.dueDate < today && t2.status !== "DONE" && t2.status !== "CANCELED");
       }
       return formatSuccess(tasks);
@@ -43888,7 +43909,7 @@ function registerTools(server, client) {
     baseBranch: exports_external.string().default("main").describe("Base branch for the worktree"),
     branch: exports_external.optional(exports_external.string()).describe("Branch name for the task worktree (auto-generated if omitted)"),
     description: exports_external.optional(exports_external.string()).describe("Task description"),
-    status: exports_external.optional(TaskStatusSchema2).describe("Initial status (default: IN_PROGRESS, use TO_DO for deferred worktree creation)"),
+    status: exports_external.optional(TaskStatusSchema2).describe("Initial status (default: TO_DO, use IN_PROGRESS for immediate worktree creation)"),
     projectId: exports_external.optional(exports_external.string()).describe("Project ID to associate with"),
     repositoryId: exports_external.optional(exports_external.string()).describe("Repository ID (alternative to repoPath)"),
     tags: exports_external.optional(exports_external.array(exports_external.string())).describe("Tags to add to the task"),
@@ -43904,7 +43925,7 @@ function registerTools(server, client) {
         branch: branch ?? null,
         worktreePath: null,
         description,
-        status: status ?? "IN_PROGRESS",
+        status: status ?? "TO_DO",
         projectId: projectId ?? null,
         repositoryId: repositoryId ?? null,
         tags,
@@ -44322,8 +44343,10 @@ function registerTools(server, client) {
   }, async ({ startDate, endDate, overdue }) => {
     try {
       let tasks = await client.listTasks();
-      const today = new Date().toISOString().split("T")[0];
       if (overdue) {
+        const config3 = await client.getConfig("appearance.timezone");
+        const timezone = config3?.value ?? null;
+        const today = getTodayInTimezone(timezone);
         tasks = tasks.filter((t2) => t2.dueDate && t2.dueDate < today && t2.status !== "DONE" && t2.status !== "CANCELED");
       } else {
         if (startDate) {
@@ -44735,7 +44758,7 @@ async function runMcpServer(urlOverride, portOverride) {
   const client = new FulcrumClient(urlOverride, portOverride);
   const server = new McpServer({
     name: "fulcrum",
-    version: "1.14.1"
+    version: "2.0.0"
   });
   registerTools(server, client);
   const transport = new StdioServerTransport;
@@ -47084,7 +47107,7 @@ var marketplace_default = `{
       "name": "fulcrum",
       "source": "./",
       "description": "Task orchestration for Claude Code",
-      "version": "1.14.1",
+      "version": "2.0.0",
       "skills": [
         "./skills/fulcrum"
       ],
@@ -48272,7 +48295,7 @@ function compareVersions(v1, v2) {
 var package_default = {
   name: "@knowsuchagency/fulcrum",
   private: true,
-  version: "1.14.1",
+  version: "2.0.0",
   description: "Harness Attention. Orchestrate Agents. Ship.",
   license: "PolyForm-Perimeter-1.0.0",
   type: "module",
@@ -48288,24 +48311,31 @@ var package_default = {
     "db:studio": "drizzle-kit studio"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.1.34",
     "@atlaskit/pragmatic-drag-and-drop": "^1.7.7",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^1.1.0",
     "@azurity/pure-nerd-font": "^3.0.5",
     "@base-ui/react": "^1.0.0",
     "@dagrejs/dagre": "^1.1.8",
+    "@fontsource-variable/ibm-plex-sans": "^5.2.8",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
     "@hono/node-server": "^1.19.7",
     "@hono/node-ws": "^1.2.0",
     "@hugeicons/core-free-icons": "^3.0.0",
     "@hugeicons/react": "^1.1.3",
+    "@mdx-js/mdx": "^3.1.1",
+    "@modelcontextprotocol/sdk": "^1.11.0",
     "@monaco-editor/react": "^4.7.0",
     "@octokit/rest": "^22.0.1",
+    "@opencode-ai/sdk": "^1.1.34",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-query": "^5.90.12",
     "@tanstack/react-router": "^1.141.8",
+    "@types/mdx": "^2.0.13",
     "@uiw/react-markdown-preview": "^5.1.5",
+    "@uiw/react-md-editor": "^4.0.11",
     "@xterm/addon-clipboard": "^0.2.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",
@@ -48322,6 +48352,7 @@ var package_default = {
     glob: "^13.0.0",
     hono: "^4.11.1",
     i18next: "^25.7.3",
+    "lucide-react": "^0.511.0",
     mobx: "^6.15.0",
     "mobx-react-lite": "^4.1.1",
     "mobx-state-tree": "^7.0.2",