# AI Work Hub

**One private memory layer for every AI tool you use.**

AI Work Hub is an open-source, local-first workspace index for developers, researchers and teams who move between repositories and AI assistants. It turns allowlisted projects, Git state, decisions, tasks and approved AI-session metadata into searchable context through a dashboard, CLI and Model Context Protocol (MCP) server.

Your source stays on your computer. There is no Work Hub cloud index, account or telemetry.

No OpenAI, Anthropic or other provider API key is required. A clone derives its own paths and private runtime from the current operating-system user; repository files contain no machine-specific config, database, logs or credentials.

![AI Work Hub dashboard with synthetic example data](docs/assets/dashboard.png)

## What this gives you

- **Continue work in any AI client.** Search the same local project context from Codex, Claude or another MCP client instead of explaining the repository again.
- **Find decisions, not only files.** Capture a decision, task, note or blocker and retrieve it beside source context later.
- **Build bounded context bundles.** Select a project and task, then copy a concise evidence bundle into any AI prompt.
- **Carry context between people and tools.** Save, reopen, import and export redacted Markdown handoffs with portable source references.
- **Reuse the context that matters.** Save recurring searches and pin important sources without copying document bodies into organizational lists.
- **See the whole workspace.** Git and manifest projects, recent changes, open work and session metadata appear in one dashboard.
- **Understand code relationships.** An optional GitNexus adapter adds local dependency-aware queries, symbol context, impact and changed-code analysis for selected Git repositories.
- **Coordinate work across AI tools.** Put durable tasks on one board, assign portable Codex/Claude/generic profiles and prepare isolated Git worktrees for parallel delivery.
- **Merge only proven work.** Run selected repository verification scripts, inspect committed-diff evidence and require exact-ID approval before a clean fast-forward merge.
- **Automate deliberately.** Record provider-neutral usage counters and execute an approved n8n webhook plan exactly once without retaining response bodies or credentials.
- **Stop babysitting the indexer.** The user service starts at login, restarts after crashes, stores filesystem events durably and performs a background reconciliation after downtime.

## Privacy model

AI Work Hub only reads roots you explicitly allow. It excludes Git internals, dependencies, caches, builds, `.env*`, key material, credential-named files and supported secret patterns. Symlinks cannot escape an allowlisted root. Codex and Claude adapters retain only approved session metadata—never prompts, responses or tool output. The indexer never modifies source files. A user-started orchestration run creates a separate Git worktree; only an exact-ID-approved, clean, verified run can fast-forward the selected repository. If explicitly enabled, the separate GitNexus executable writes its own `.gitnexus/` graph and local Git exclude metadata; it does not rewrite source bodies.

The dashboard binds to `127.0.0.1`, enables no CORS, uses strict browser security headers and protects mutations with same-origin CSRF validation. Runtime files and backups are owner-only where the operating system supports POSIX permissions.

## Supported platforms

- macOS: launchd user service with `KeepAlive`
- Linux: systemd user service with `Restart=always`
- Windows: per-user Task Scheduler job with restart-on-failure
- Node.js 24 LTS

The core index, CLI and dashboard are cross-platform. Platform-specific service definitions are generated at install time; no username or machine path is embedded in the repository.

## Quick start from source

```sh
git clone https://github.com/davidvuy/ai-work-hub.git
cd ai-work-hub
npm ci
npm run verify
npm link

ai-work-hub setup --root "$HOME/Projects"
ai-work-hub connect codex --apply
ai-work-hub open
```

Repeat `--root` to include more than one workspace:

```sh
ai-work-hub setup --root "$HOME/Projects" --root "/path/to/research"
```

`setup` validates the roots in the interactive CLI process, derives the profile and all runtime paths from the current computer user, creates a private runtime, installs the per-user service and starts the first scan in the background. It then waits for the dashboard and reports a separate `serviceRootAccess` result produced inside the installed service. A successful interactive directory check is not presented as proof that launchd, systemd or Task Scheduler can read the same root. `ready` means every configured root has service-context evidence; `degraded` identifies blocked roots; `pending` means that evidence was not complete before setup returned. Use `ai-work-hub doctor` or the System page to inspect and recheck a root. Pass `--name "Your Name"` only when you want a different dashboard name. It never scans the entire home directory unless that directory is explicitly supplied.

Git is resolved to a canonical absolute executable and never from a repository-local command shadow. Standard system, Homebrew, MacPorts, Nix-profile, Scoop, Chocolatey and user Git-for-Windows locations are recognized. For another managed installation, set `AI_WORK_HUB_GIT_EXECUTABLE` to its absolute executable before `setup` or `service install`; Windows overrides must point to a native PE `.exe`. Installation validates the complete boundary, runs one bounded shell-free `git --version` identity probe and retains only the canonical path outside every configured root plus the product/runtime directories. Later service restarts reload that path from the owned service definition and repeat the validation/probe; setting the variable explicitly to an empty value clears it. Every scanner and orchestration use revalidates it against all configured roots and managed run workspaces.

`connect codex --apply` idempotently registers the local MCP server. Use `connect claude --apply` for Claude Code, or run `ai-work-hub connect cursor` to print the copy-ready Cursor configuration. AI clients and the always-on indexer are independent: the service keeps context current, while MCP lets each supported client query it.

The interface is currently English. `--locale` controls personalized number/time formatting and is reserved for additional translations.

`npm run verify` builds and tests the product and includes `verify:public` plus `verify:history`. The publication gates reject committed runtime artifacts, secrets, personal home/volume paths, non-example email addresses, credential-bearing URLs, unexpected external runtime endpoints, unreviewed install scripts and dependencies outside the public npm registry. The history gate additionally inspects every blob and commit reachable from the release branch, requires the declared public maintainer identity and never prints a matched secret value.

To configure without a background service:

```sh
ai-work-hub setup --root "$HOME/Projects" --no-service
ai-work-hub scan
```

## Everyday workflow

```sh
ai-work-hub open
ai-work-hub search "authentication decision"
ai-work-hub projects
ai-work-hub project-status my-app
ai-work-hub agents create --name "Repository reviewer" --provider generic --description "Reviews bounded changes" --instructions "Inspect the diff and run verification"
ai-work-hub work create --project my-app --title "Ship change" --description "Implement, verify and document" --profile 1
ai-work-hub work status 1 ready
ai-work-hub runs start 1 --profile 1
ai-work-hub memory add --type decision --project my-app --title "Use passkeys" --body "Reason and trade-offs"
ai-work-hub explain "$HOME/Projects/my-app/src/auth.ts"
ai-work-hub roots add "$HOME/Research"
ai-work-hub backup
ai-work-hub backups
ai-work-hub doctor
```

The dashboard provides overview metrics, smart search with source references, saved searches, pinned sources, saved/importable context bundles, project/Git status, a universal agent work board, portable profiles, isolated validation/review/merge runs, body-free usage status, approved n8n webhook plans, append-only activity, durable notes/decisions/tasks/blockers, AI-client setup, managed workspace roots, service health, bounded operational logs, safe reindex scheduling, session-adapter status, verified backups, local digests and metadata-only exports.

## Optional code intelligence

AI Work Hub integrates with a separately installed, pinned `gitnexus@1.6.9` executable. GitNexus is not bundled because its PolyForm Noncommercial license differs from AI Work Hub's MIT license. Review the upstream license before use, then install and opt in a selected repository:

```sh
npm install -g gitnexus@1.6.9
ai-work-hub service restart
ai-work-hub code-intel analyze my-app --accept-noncommercial-license
ai-work-hub code-intel query "where is authentication authorized" --project my-app
ai-work-hub code-intel cancel JOB_ID --confirm JOB_ID
ai-work-hub code-intel disable-auto-refresh my-app
```

The graph stays in the repository's ignored `.gitnexus/` directory. Analysis uses `--index-only`: Work Hub does not enable embeddings, generate AI instruction files, run client setup or upload source. After the accepted first build, the always-on daemon refreshes only the selected repositories. Cancellation waits for a durable terminal state; refresh opt-out leaves the existing graph queryable. Status and graph controls are also available on the Projects page and through MCP. See the complete [GitNexus integration and license boundary](docs/GITNEXUS.md).

## Always-on behavior

- New filesystem events are coalesced in a durable SQLite queue and survive daemon restarts.
- Each configured root is watched in its own child process; a native watcher that cannot register falls back to policy-pruned metadata polling, and an unresponsive subdirectory is reported as degraded without blocking the dashboard, healthy files or other roots. Supervised external roots receive a bounded one-minute read window while subtrees remain bounded to ten seconds. Incomplete traversals retain existing records and assignments, suppress false deletes and retry the failed area after a cooling-down boundary.
- Ordinary file events continue during quiet hours; only an explicit pause stops queue processing.
- The OS supervisor restarts the daemon after a crash.
- An owner-only process lock prevents a manually started daemon from competing with the supervised daemon; stale crash locks recover automatically.
- A missing or stale index triggers a background reconciliation without delaying dashboard health.
- Queue overflow or repeated event failures mark a full reconciliation as required instead of silently losing correctness.
- Manual scans detect the active daemon and schedule its single writer instead of competing with it; explicit reconciliation begins immediately when indexing is eligible and otherwise remains visibly queued.
- Unavailable external roots are retried every minute.
- Verified backups and daily digests run automatically with bounded retention.

## Workspace access after installation

Operating-system privacy controls can treat the always-on service differently from the terminal that ran `setup`. The System page and `ai-work-hub doctor` therefore show the persisted service-context result for every configured root: the reason, platform guidance code, last check, last successful read and whether existing indexed records were retained. A blocked check never claims that current files are indexed, and it does not delete previously indexed records.

After changing an operating-system permission or reconnecting a volume, select **Recheck access** beside that root on the System page. The request is executed by the running service, persisted and read back before the interface reports success. If the dashboard is unavailable, restart the owned user service and run `ai-work-hub doctor` again.

- **macOS removable volume:** open **System Settings > Privacy & Security > Files and Folders** and enable removable-volume access for the executable that owns the installed Work Hub service when macOS lists it. If the selected location is protected more broadly, use **Full Disk Access** for that same service executable. Granting access only to the terminal is not service proof. Restart or recheck afterward.
- **macOS protected internal folder:** open **System Settings > Privacy & Security > Full Disk Access**, allow the executable that owns the installed Work Hub service, then restart or recheck. Prefer a less-protected workspace root when broad access is unnecessary.
- **Windows:** verify that the root is mounted and readable by the current account. If Controlled Folder Access blocks it, use **Windows Security > Virus & threat protection > Ransomware protection > Allow an app through Controlled folder access** for the installed Work Hub runtime, then restart or recheck.
- **Linux:** verify that the mount exists and that the user service account has directory traversal/read access through ownership, group membership or ACLs. Remember that a systemd user service may have a different environment from an interactive shell; restart or recheck after repairing the mount or permissions.

The automated checks exercise the bounded probe, persistence, API and browser flow with synthetic roots. Physical launchd access to an actual removable volume still requires machine-level validation and remains a stable-release gate.

A computer that is powered off cannot index events in real time. When it starts again, the scheduled reconciliation catches up.

## Recovery

Create and inspect recovery points with `ai-work-hub backup`, `ai-work-hub backups` and `ai-work-hub verify-backup FILENAME`. Guided restore is CLI-only and requires the selected filename twice:

```sh
ai-work-hub restore FILENAME --confirm FILENAME
```

Restore preflights first, stops only the matching active user service, creates a verified safety backup, swaps atomically, rolls back on validation failure and schedules a full reconciliation. Keep the reported `workhub-pre-restore-…sqlite3` file until the restored workspace has been reviewed.

## MCP integration

Let Work Hub generate the correct absolute-path setup for the current machine:

```sh
ai-work-hub connect
ai-work-hub connect codex --apply
ai-work-hub connect claude --apply
ai-work-hub connect cursor
```

For a generic client, the generated configuration has this shape:

```json
{
  "command": "/absolute/path/to/ai-work-hub",
  "args": ["mcp"]
}
```

On Windows the generated plan safely wraps the installed `.cmd` launcher through `cmd.exe`. Automatic registration never invokes a shell on macOS or Linux and uses argument arrays on every platform.

Available tools:

- `search_context`, `list_projects`, `project_status`, `recent_changes`
- `get_context_bundle`, `save_context_bundle`, `list_context_bundles`, `get_saved_context_bundle`
- `save_search`, `list_saved_searches`, `pin_source`, `list_pinned_sources`
- `list_memory`, `health`
- `capture_note`, `capture_decision`, `capture_task`, `capture_blocker`
- `update_memory_status`
- `create_agent_profile`, `list_agent_profiles`, `manage_agent_profile`
- `create_work_item`, `list_work_items`, `manage_work_item`, `manage_agent_run`
- `record_usage`, `usage_status`, `list_activity`
- `manage_automation`
- `code_intelligence_status`, `code_intelligence_analyze`, `code_intelligence_control`
- `code_intelligence_query`, `code_intelligence_context`, `code_intelligence_impact`, `code_intelligence_changes`

Most MCP mutations create private Work Hub records. `manage_agent_run` can prepare a worktree, execute explicitly accepted repository scripts and fast-forward merge only after recorded validation, review and exact-ID approval. `manage_automation` can cause an external webhook side effect only after a separate exact-ID plan approval. Both tools advertise destructive/open-world hints and fail closed on missing confirmation.

## Universal agent work

The Work page and `agents`, `work`, `runs`, `usage`, `automations` and `activity` CLI groups share the same SQLite records. Preparing a run returns an isolated workspace path; use that path as the working directory for Codex, Claude or another tool. AI Work Hub does not silently start an agent or give it credentials. After the agent commits its change:

```sh
ai-work-hub runs validate 1 --script verify --accept-execution-risk
ai-work-hub runs review 1
ai-work-hub runs approve 1 --confirm 1
ai-work-hub runs merge 1 --confirm 1
ai-work-hub runs cleanup 1 --confirm 1
```

Profiles and connectors can be disabled without deleting their history. Dependencies can be removed before execution, active runs can be exact-ID cancelled while retaining their worktree for inspection, and draft/approved webhook plans can be exact-ID cancelled. Cancelled run workspaces are deleted only by the separate confirmed cleanup command.

Validation runs only named scripts already present in that worktree's `package.json`, in a bounded environment with an isolated home directory. Work Hub stores script name, outcome, exit code, duration and an output SHA-256—not console output. Review records relative changed filenames, commit count, cleanliness and short statistics. Merge refuses dirty worktrees, a dirty target repository, a changed target HEAD, missing successful validation, missing committed changes or a mismatched confirmation. Cleanup is separately exact-ID confirmed, accepts only terminal runs, re-verifies the managed path, branch and cleanliness, removes the Git worktree and isolated validation home, then persists a body-free `run.cleaned` receipt.

n8n automation uses the same evidence-first lifecycle. Connector records contain a validated base URL and optional environment-variable name, never the credential value. A trigger is a bounded JSON draft under `/webhook/…`, must be approved with its exact plan ID, is atomically claimed once and stores only HTTP status plus a payload hash; response bodies are discarded.

Execution requires the same plan ID again so a stale UI, copied command or unrelated local caller cannot trigger a different approved plan:

```sh
ai-work-hub automations approve 1 --confirm 1
ai-work-hub automations execute 1 --confirm 1
```

## Portable context bundles

The dashboard context builder can save a selected project/task handoff, reopen it later, download Markdown or import an existing Markdown handoff. Generated bundles repeat secret redaction and replace sources below the project root with references such as `./src/auth.ts` so local usernames and root locations are not required on another machine.

The same workflow is available without a browser:

```sh
ai-work-hub bundle create --title "Authentication handoff" --project my-app --task "finish passkey rollout"
ai-work-hub bundle list
ai-work-hub bundle export 1 --output ./authentication-handoff.md
ai-work-hub bundle import ./teammate-handoff.md --title "Teammate handoff" --project my-app
ai-work-hub bundle delete 1 --confirm 1
```

Bundle deletion removes only the private Work Hub record. It never deletes or modifies a referenced source file.

## Reusable retrieval

Name searches you run repeatedly and keep high-value sources visible:

```sh
ai-work-hub saved-search create --title "Auth decisions" --query "authentication decision" --project my-app --kind file
ai-work-hub saved-search list
ai-work-hub saved-search run 1
ai-work-hub pins add 42
ai-work-hub pins list
```

The dashboard exposes the same workflow beside search results. CLI removal requires the exact record identifier again, for example `saved-search delete 1 --confirm 1` or `pins remove 42 --confirm 42`. Pin and saved-search listings are bounded local metadata; they do not duplicate indexed document bodies.

CSV, XML, SVG, Jupyter notebooks and the documented source/configuration extensions use the normal bounded text and secret-policy path. PDF, Office, image, video and archive formats remain metadata-only.

## CLI reference

```text
ai-work-hub setup --root PATH [--root PATH] [--name NAME] [--locale auto|en|nl] [--port N]
ai-work-hub init
ai-work-hub roots list|add|remove
ai-work-hub connect [codex|claude|cursor|generic] [--apply]
ai-work-hub scan [--dry-run] [--max-files N]
ai-work-hub explain PATH
ai-work-hub status
ai-work-hub search QUERY [--project NAME]
ai-work-hub projects
ai-work-hub project-status [NAME]
ai-work-hub memory list|add|status
ai-work-hub bundle create|list|show|import|export|delete
ai-work-hub saved-search create|list|run|delete
ai-work-hub pins list|add|remove
ai-work-hub agents create|list|enable|disable|export
ai-work-hub work create|list|status|depends-on|remove-dependency
ai-work-hub runs list|start|validate|review|approve|merge|cancel|cleanup
ai-work-hub automations create-connector|list-connectors|enable-connector|disable-connector|create-plan|list-plans|approve|execute|cancel
ai-work-hub code-intel status|analyze|cancel|disable-auto-refresh|query|context|impact|changes
ai-work-hub adapters
ai-work-hub scan-sessions [--full]
ai-work-hub pause|resume
ai-work-hub reindex|repair-index
ai-work-hub open
ai-work-hub digest|backup|backups|verify-backup|restore|export
ai-work-hub doctor
ai-work-hub service install|status|restart|uninstall --keep-data
ai-work-hub mcp
```

## Development

```sh
npm run verify          # syntax, lint, strict types, unit/integration tests, build
npm run verify:runtime  # real daemon pause/resume, watcher, persistence and restart
npm run verify:gitnexus # real isolated GitNexus 1.6.9 acceptance (requires GITNEXUS_ENTRY)
npm run verify:integrated # daemon + browser + API + CLI + MCP + watcher + GitNexus together
npm run test:coverage   # coverage report
npm run e2e             # Chromium, Firefox, WebKit, mobile, Axe, visuals
npm run perf:10k        # reproducible 10,000-file workload
npm run package:check   # inspect the public npm tarball
```

See [architecture](docs/ARCHITECTURE.md), [acceptance matrix](docs/ACCEPTANCE_MATRIX.md), [operations](docs/OPERATIONS.md), [privacy](docs/PRIVACY.md), [threat model](docs/THREAT_MODEL.md), [GitNexus integration](docs/GITNEXUS.md), [product gaps and roadmap](docs/PRODUCT_GAPS.md), the base [88-point security/correctness audit](docs/SECURITY_AUDIT_2026-07-29.md), its [22-point lifecycle addendum](docs/LIFECYCLE_AUDIT_2026-07-30.md) and the measured [validation report](docs/VALIDATION_REPORT.md).

Tagged GitHub releases publish the npm tarball together with a CycloneDX SBOM and `SHA256SUMS` manifest. Platform signing/notarization and a Windows installer remain tracked distribution work rather than completed claims.

## Contributing and security

Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing behavior and report vulnerabilities through [SECURITY.md](SECURITY.md), not a public issue.

AI Work Hub is available under the [MIT License](LICENSE).