Lucidity

Lucidity's local personal agent, CLI, and MCP server. Manage tasks, projects, milestones, comments, and local markdown notes from an MCP client, or run Lucid on your machine for scheduled briefings and interactive chat.

Install

Requires Node.js 22 or newer.

npm install -g @opencorelabs/[email protected]
lucidity setup

The package includes the CLI, daemon, MCP server, and their internal libraries. It also provides the lucidity-daemon and lucidity-mcp commands.

MCP server

After connecting your account with lucidity setup, select Use Lucidity in Claude Code and/or Use Lucidity in Codex to add the tools automatically. You can select both; each client keeps its own account and subscription. For an already configured computer, run lucidity setup again for the app choices, or run lucidity setup-mcp to connect detected clients. No token copying is needed. Open a new client session afterward and approve any tool permissions it requests. See automatic setup and recovery.

Manual setup for other MCP clients

Generate an API key in the Lucidity app under Settings → API Key. Configure your MCP client to launch lucidity mcp with that key in LUCIDITY_API_KEY. For clients using JSON configuration:

{
  "mcpServers": {
    "lucidity": {
      "command": "npx",
      "args": ["-y", "@opencorelabs/lucidity", "mcp"],
      "env": {
        "LUCIDITY_API_KEY": "luc_your_api_key_here",
        "LUCIDITY_API_URL": "https://api.lucidity.my"
      }
    }
  }
}

Optional environment variables:

• LUCIDITY_NOTES_PATH: an absolute path to your markdown notes directory.
• LUCIDITY_VAULT_PATH: an absolute path to Lucid's memory directory.

The MCP server itself does not require Claude Code. Keep credentials in your personal client configuration rather than your repository.

Connect a computer

A computer is optional. The phone can manage tasks, projects, collaboration, and journal storage without it. Connecting this agent adds AI conversations and any local capabilities you explicitly enable.

The package installs exact Claude Agent SDK and Codex runtime versions, including the native binaries for your operating system. Do not omit optional dependencies. A separate global provider CLI is only needed to establish or refresh its login; it does not choose the runtime used by Lucidity.

Authenticate the provider you intend to use on the same computer/account:

• Claude: sign in with Claude Code using a supported Claude subscription.
• Codex: run codex login using ChatGPT authentication.

On Windows, install Git for Windows (including Git Bash) for Claude and local coding tools. The initial Windows pilot runs the agent in a terminal; automatic background installation, status, and uninstall currently support macOS only. Closing the terminal or sleeping the computer makes its AI features unavailable. Core mobile data remains available through the hosted API.

Run lucidity setup to open the guided page. Sign in at lucidity.my and approve this computer, then select an authenticated provider. If you use both Claude and Codex, keep both provider logins on the computer; Lucid uses the provider selected for each conversation. The optional client checkboxes can connect Lucidity's MCP tools to both apps regardless of that default.

Review task access and scheduled work, which start off, then finish setup to start the foreground agent. No API key or JSON editing is needed. The connection is saved under your user profile in .lucidity/config.json; keep it private.

Keep the terminal open on Windows. Use Ctrl+C to stop the agent and lucidity --deliver stdout to start it again. On the phone, use the same Lucidity account and open Connect a computer to see the computer and provider status. AI uses the selected provider's subscription allowance; Lucidity does not switch providers or fall back to API billing automatically.

Existing configured users can run lucidity setup-mcp claude codex to register both clients without pairing again or starting another daemon. Manual configuration for advanced or self-hosted setups remains in the daemon guide.

On macOS, lucidity install registers and starts a background agent at login. Use lucidity status, lucidity chat, and lucidity uninstall to manage it. See the daemon guide for permissions, schedules, repositories, and provider configuration.

Source and license

Source repository. The agent and bundled Lucidity libraries are distributed under AGPL-3.0. Source is included with the package; third-party dependencies retain their own licenses.

Building a release

From the repository root, install workspace dependencies and run:

# On Apple Silicon macOS, build speech support for the public release first:
npm run build:speech --prefix apps/daemon
npm run pack:npm
npm run verify:npm
npm run verify:npm -- --local

This builds the agent and its workspace dependencies, vendors the internal libraries as local file dependencies with a private Zod 3 copy for MCP, writes the publishable archive to dist/npm/, and verifies the CLI and MCP server from isolated global and local installations. Publish that archive with npm publish dist/npm/opencorelabs-lucidity-0.9.5.tgz --access public. The private workspace packages do not need separate npm publications.

Set LUCIDITY_NPM_VERIFY_CACHE to an absolute directory to reuse package downloads between verification runs. Each run still installs into a fresh temporary prefix, refreshes registry metadata and checks package integrity. The cache must be outside that temporary installation and is retained after verification. Without this variable, each run uses its own disposable cache.

LUCIDITY_NPM_VERIFY_CACHE="$PWD/.context/npm-verify-cache" npm run verify:npm
LUCIDITY_NPM_VERIFY_CACHE="$PWD/.context/npm-verify-cache" npm run verify:npm -- --local

When the speech helper has been built, the archive includes its executable, corresponding Swift source, pinned FluidAudio dependency and third-party notices. The helper runs only on Apple Silicon macOS; other platforms retain the regular CLI and MCP experience. The install verifier checks its startup without downloading models.

The npm release checks workflow runs when an npm-v* tag is pushed, or when manually started for a release candidate. Ordinary pull requests and branch pushes do not start the cross-platform matrix. To check a candidate on main before tagging it:

gh workflow run npm-package.yml --ref main

Select the candidate branch or tag with --ref when it is elsewhere, and confirm the run's commit matches the source being released. Pushing a release tag already starts a run, so no additional manual dispatch is needed for that tag. Review the complete matrix result before publishing the release archive.

The workflow globally and locally installs the same archive on Windows, macOS, and Linux using Node.js 22. It verifies CLI/imports, platform-specific provider binaries (and absence of foreign-platform binaries), Codex app-server initialization, and both MCP entry points without running inference. This is distinct from authenticated physical-device acceptance.