How navskh/im works
1. Overall shape
- This is a local-first task management system built as a Next.js 16 + React 19 web app, plus a Node-based CLI and a stdio MCP server.
- The architecture is centered around a single local data store and a set of shared server-side libraries that power the UI, CLI commands, sync, AI automation, and external agent integration.
2. Primary entrypoints
- bin/im.js is the installed CLI entrypoint (im start, im watch, im sync, im mcp).
- The browser UI is served from the Next.js App Router under src/app.
- src/lib/mcp/server.ts exposes the MCP server for external AI clients.
- src/lib/watcher.ts and src/lib/scheduler.ts support background automation from the CLI side.
3. User interface boundary
- The UI is organized as a dashboard/workspace system with reusable panels and tabs.
- Major UI areas include:
- dashboard views for projects and status summaries,
- a workspace with brainstorming, project tree, and task detail panes,
- task-specific chat and prompt editing,
- modals for AI policy, auto-distribution, sync results, and confirmations.
- The architecture is intentionally panel-driven, so a single project can be opened in a tabbed workspace while multiple projects remain accessible.
4. Core domain model
- The main domain hierarchy is:
- Project
- Sub-project
- Task
- Task prompt
- Task conversation
- Brainstorm notes
- Global memo
- Task status is a workflow state machine: idea → writing → submitted → testing → done/problem.
- Archived tasks are preserved as a distinct lifecycle branch rather than being hard-deleted immediately.
5. Persistence layer
- Data is stored locally in SQLite via sql.js under ~/.idea-manager/data/, so the app is designed to work offline and without native DB bindings.
- src/lib/db/schema.ts defines the schema, while src/lib/db/queries/* separates persistence concerns by entity:
- projects, sub-projects, tasks,
- task prompts,
- task conversations,
- brainstorms,
- global memo.
- This makes the database layer the primary boundary between UI/API logic and durable state.
6. API layer
- Server functionality is exposed through Next.js API routes under src/app/api.
- The route set is organized by capability rather than by page:
- project CRUD and nested project/task operations,
- brainstorming and task distribution,
- archive handling,
- filesystem/tree inspection,
- global memo,
- health and sync endpoints.
- These route handlers are the main server-side façade for the UI and likely the only HTTP surface the browser talks to.
7. Brainstorming → task structuring workflow
- A key flow is converting free-form brainstorming into structured work:
- brainstorm content is captured in the workspace,
- AI-assisted distribution proposes sub-project/task placement,
- the user previews/edits the result,
- tasks receive prompts and can then be executed by an agent.
- This flow is reflected in both the UI components and API routes for brainstorm, auto-distribute, and apply-distribute.
8. AI agent integration
- src/lib/ai/client.ts and src/lib/ai/agents.ts abstract over multiple AI CLIs, specifically Claude, Gemini, and Codex.
- The project can select an agent per project, and that choice affects:
- AI chat inside task context,
- watch-mode execution,
- prompt refinement and distribution workflows.
- The system is built around invoking external CLI agents rather than hosting model inference itself.
9. MCP server boundary
- The MCP layer exposes task/project context to outside tools through standard MCP tools like listing projects, retrieving context, fetching the next task, updating status, and reporting completion.
- Conceptually, MCP is an integration boundary that lets autonomous agents operate on the same underlying task database as the UI and CLI.
10. Sync and portability
- Cross-machine sync is implemented as data export/import over Git rather than a centralized backend.
- src/lib/sync/exporter.ts, importer.ts, git.ts, and index.ts form the sync subsystem.
- The workflow is:
- export local state,
- commit/push to a private repo,
- pull on another machine,
- import into the local SQLite store.
- This preserves the local-first model while allowing multi-PC use.
11. File system / workspace linkage
- The app can link projects to real directories on disk.
- src/app/api/filesystem/*, src/lib/utils/paths.ts, and the directory-picker/file-tree UI indicate a clear boundary between managed metadata in SQLite and the actual project files on disk.
- The linked filesystem context is important for task execution, AI chat working directory, and tree browsing.
12. Background automation
- Two automation paths exist outside the UI:
- watch mode auto-executes submitted tasks through AI CLI tooling,
- scheduler sends daily morning notifications and other time-based triggers.
- These are part of the product’s operational layer, separate from interactive UI flows.
13. Application shell and PWA-like delivery
- The app ships with a manifest and service worker in public/, and the README describes launching in Chrome/Edge --app mode.
- That means the “desktop-like” experience is delivered as a browser app with lightweight app-shell behavior, not a native desktop runtime.
14. How to think about the main boundaries
- There are three important architectural boundaries:
- presentation: Next.js pages/components,
- domain/data: shared DB queries and sync logic,
- automation/integration: AI CLIs, MCP server, watcher, scheduler, and Git sync.
- Almost every feature flows through local persistence first, then through one of those integration layers when external action is needed.
Main entry points: index.ts Queries · WorkspacePanel.tsx Workspace · im.js CLI entry · server.ts MCP server
Components 20
Presentation
Next.js app shell and reusable workspace panels
- Web app · Browser-delivered app shell and routing entry
src/app/page.tsx - Project page · Project workspace page for a single opened project
src/app/projects/[id]/page.tsx - Dashboard · Projects and status overview surface
src/components/dashboard/DashboardPanel.tsx - Workspace · Tabbed workspace container for project-focused panels
src/components/workspace/WorkspacePanel.tsx - Task panels · Project tree, task detail, prompt editing, status flow, and task chat
src/components/task/TaskDetail.tsx - Brainstorming · Free-form idea capture and resizing editor
src/components/brainstorm/Editor.tsx - Modals · AI policy, auto-distribute, sync results, and confirmation dialogs
src/components/ui/AutoDistributeModal.tsx
HTTP API
Route handlers that expose server capabilities to the UI
- Projects API · Project CRUD and nested sub-project/task operations
src/app/api/projects/route.ts - Brainstorm API · Brainstorm capture and task distribution endpoints
src/app/api/projects/[id]/brainstorm/route.ts - Archive API · Archive lifecycle operations for tasks and records
src/app/api/archive/route.ts - Filesystem API · Linked directory access and tree inspection
src/app/api/filesystem/route.ts - Sync API · Export/import sync operations exposed to the UI
src/app/api/sync/route.ts
Domain & Data
Shared local-first persistence, sync, and app logic
- Schema · Local sql.js schema for projects, tasks, prompts, conversations, brainstorms, and memo
src/lib/db/schema.ts - Queries · Entity-specific database access for projects, sub-projects, tasks, prompts, conversations, brainstorms, and memo
src/lib/db/index.ts - Sync engine · Export/import and Git-based portability workflow
src/lib/sync/index.ts
Automation & Integration
CLI entrypoints and external agent boundaries
- CLI entry · Installed command for start, watch, sync, and MCP modes
bin/im.js - AI layer · Abstraction over Claude, Gemini, and Codex CLI agents
src/lib/ai/client.ts - MCP server · External agent integration over MCP tools
src/lib/mcp/server.ts - Watcher · Background execution for submitted tasks
src/lib/watcher.ts - Scheduler · Time-based triggers such as morning notifications
src/lib/scheduler.ts
Connections 22
- CLI entry → Watcher: start/watch · CLI launches background task automation
- CLI entry → MCP server: mcp · CLI exposes the stdio MCP mode
- CLI entry → Sync API: sync · CLI can drive sync workflows through shared logic
- Web app → Dashboard: renders · App shell presents the dashboard surface
- Web app → Project page: routes to · App Router serves the project workspace page
- Project page → Workspace: hosts · Project page contains the tabbed workspace
- Workspace → Task panels: shows · Workspace organizes project tree and task-centric panels
- Workspace → Brainstorming: includes · Workspace supports brainstorming capture
- Workspace → Modals: opens · Workspace uses modal dialogs for actions and results
- Projects API → Queries: reads/writes · Project and nested entity routes persist through queries
- Brainstorm API → Queries: updates · Brainstorm and distribution endpoints persist structured work
- Archive API → Queries: archives · Archive routes change task lifecycle state
- Filesystem API → Queries: links context · Filesystem routes coordinate metadata with local project context
- Sync API → Sync engine: uses · HTTP sync surface delegates to export/import engine
- Queries → Schema: implements · Query layer operates on the local SQLite schema
- Sync engine → Schema: exports/imports · Sync reads and restores the same local store
- MCP server → Queries: context tools · MCP tools read and update the shared task database
- MCP server → AI layer: agent actions · External agents operate through the same AI abstraction
- Watcher → AI layer: executes · Watch mode runs submitted tasks via CLI agents
- Scheduler → Queries: triggers · Scheduler reads local state for notifications and automation
- Task panels → Queries: manages · Task UI is backed by shared persistence
- Brainstorming → Brainstorm API: submits · Brainstorm content flows into distribution and structuring routes