# Quickstart

> Run `ok init`, `ok start --open`, verify the editor loads, and confirm MCP tools respond from a connected agent.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `packages/cli/src/commands/init.ts`
- `packages/cli/src/commands/start.ts`
- `packages/server/src/init-project.ts`
- `packages/cli/src/cli.ts`
- `docs/content/get-started/quickstart.mdx`
- `docs/content/reference/cli.mdx`

---

---
title: "Quickstart"
description: "Run `ok init`, `ok start --open`, verify the editor loads, and confirm MCP tools respond from a connected agent."
---

The `ok` CLI scaffolds a project with `ok init` (`.ok/` config, git, MCP registration for detected editors) and boots a per-project Hocuspocus collaboration server plus an auto-spawned `ok ui` web editor with `ok start`. Agents connect through the `open-knowledge` MCP server (`ok mcp`) that `ok init` registers; read tools like `exec` work server-free, while writes route through the running server.

## Prerequisites

<Note>
Install **Node.js 24+** and **git** before using the CLI path. See [Installation](/installation) for npm install, desktop DMG, and contributor toolchain details.
</Note>

| Requirement | Used for |
| --- | --- |
| Node.js 24+ | `npm install -g @inkeep/open-knowledge` and the `npx` MCP launch chain |
| `git` | `ok init` calls `ensureProjectGit`; timeline, shadow-repo, and sync features depend on it |

## Runtime layout

```mermaid
sequenceDiagram
  participant You
  participant CLI as ok CLI
  participant Server as Hocuspocus server
  participant UI as ok ui
  participant Agent as Agent editor
  participant MCP as open-knowledge MCP

  You->>CLI: ok init
  CLI->>CLI: Scaffold .ok/, git, MCP configs, skills
  You->>CLI: ok start --open
  CLI->>Server: bootServer (collab + HTTP API)
  CLI->>UI: spawnOkUi (sibling process)
  CLI-->>You: Banner with Editor URL
  CLI-->>You: openBrowser(localUrl)
  Agent->>MCP: stdio (ok mcp)
  MCP->>MCP: exec (server-free reads)
  MCP->>Server: write / edit / search (server-routed)
  UI->>Server: Yjs CRDT sync
```

On `ok start`, the CLI also runs reclaim sweeps for MCP configs, `launch.json`, and bundled skills before the server accepts connections. These repairs are best-effort and non-blocking.

## Initialize the project

<Steps>

<Step title="Install the CLI">

<CodeGroup>

```bash title="npm (global)"
npm install -g @inkeep/open-knowledge
```

```bash title="Verify"
ok --version
```

</CodeGroup>

</Step>

<Step title="Create a project directory and run ok init">

```bash
mkdir my-knowledge-base && cd my-knowledge-base
ok init
```

`ok init` performs these actions in order:

1. Resolves the project root (promotes to a git root or ancestor `.ok/` when applicable).
2. Initializes git when no repository exists (`ensureProjectGit`).
3. Scaffolds `.ok/config.yml`, `.ok/.gitignore`, and `.okignore` via `initContent`.
4. Registers the `open-knowledge` MCP server for detected editors (Claude Code, Cursor, Codex, Claude Desktop).
5. Writes project-local skills (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`).
6. Installs the user-global `open-knowledge` skill via `npx skills`.
7. Scaffolds `.claude/launch.json` when Claude Code is detected.

<ParamField body="--no-mcp" type="flag">
Scaffold `.ok/` only; skip all MCP and skill registration.
</ParamField>

<ParamField body="--scope" type="user | project | both">
Control where MCP entries are written. Default in an interactive terminal: both user-level (`~/.claude.json`, `~/.cursor/mcp.json`, …) and project-level (`.mcp.json`, `.cursor/mcp.json`, …). Non-TTY defaults to `both`.
</ParamField>

<ParamField body="--shared" type="flag">
Commit OK config alongside content (default for fresh repos).
</ParamField>

<ParamField body="--local-only" type="flag">
Append OK artifact paths to `.git/info/exclude` so config stays per-clone.
</ParamField>

<Check>
Successful init prints **Content scaffolded at `.ok/`**, MCP registration lines for each detected editor, and **Next steps** when at least one editor was configured.
</Check>

</Step>

<Step title="Start the server and open the editor">

```bash
ok start --open
```

`ok start` requires a `.ok/` directory at the project root. Without it, the CLI exits with:

```
This directory isn't set up yet. Run `ok init` first, then `ok start` again.
```

<ParamField body="--open" type="flag">
Open the editor URL in the default browser after the server finishes initialization.
</ParamField>

<ParamField body="-p, --port" type="number">
Pin the collaboration server port. Falls back to the `PORT` environment variable; auto-allocated when unset.
</ParamField>

<ParamField body="-H, --host" type="string">
Bind host. Defaults to `localhost` (`DEFAULT_SERVER_HOST`). Override with the `HOST` environment variable.
</ParamField>

<ParamField body="--cwd" type="path">
Global flag: run against a different project directory.
</ParamField>

<Info>
`ok start` auto-spawns an `ok ui` sibling unless a UI lock is already alive or `--react-shell-dist-dir` suppresses it. The startup banner labels the editor URL **Editor:** when a UI port is resolved, otherwise it falls back to the API URL.
</Info>

</Step>

</Steps>

## Verify the editor loads

Use these checks after `ok start --open`:

| Signal | Expected result |
| --- | --- |
| Startup banner | Boxed output with `open-knowledge v<version>`, an **Editor:** URL (`http://localhost:<ui-port>`), and optionally an **API:** URL for the collab server |
| Browser | Editor shell loads at the **Editor:** URL when `--open` is set |
| `ok status` | Both lines report `alive` with pid and port |

```bash
ok status
```

<RequestExample>

```bash
ok status
```

</RequestExample>

<ResponseExample>

```text
server  alive  pid=12345 port=3847 started=2026-06-25T12:00:00.000Z
ui      alive  pid=12346 port=5173 started=2026-06-25T12:00:01.000Z
```

</ResponseExample>

An empty knowledge base shows the create screen in the editor sidebar. No markdown files are created by `ok init` alone; use an agent or `ok seed` to add content.

## Verify MCP tools from a connected agent

`ok init` registers MCP for editors it detects. Open the project folder in your agent (Claude Code, Cursor, or Codex), approve the `open-knowledge` MCP server when prompted, and run a read-only verification.

<Warning>
Cursor and other hosts may require explicit approval of a new MCP server. Approve **`open-knowledge`** — that is the `MCP_SERVER_NAME` constant wired by `ok init`.
</Warning>

Send this prompt in the agent chat:

```
List the first 5 documents you come across in this project.
```

The agent should invoke the Open Knowledge **`exec`** tool (for example `exec({ command: "ls -A" })` or `cat` on markdown files). `exec` is server-free: it reads the filesystem directly and returns enriched metadata (frontmatter, backlinks, history) for knowledge-base files.

| MCP behavior | Server required? |
| --- | --- |
| `exec`, `preview_url` | No — work with editor down |
| `search`, `links`, `history`, and other reads | Yes — route through Hocuspocus |
| `write`, `edit`, `delete`, `move`, and other writes | Yes — Hocuspocus starts on first write if not already running |

<Check>
A working MCP connection returns document paths or `exec` output referencing your project directory. An empty project may return an empty listing — that still confirms the tool responded.
</Check>

<Tip>
Set your agent to auto-approve tool calls (auto-mode, full-access, or equivalent) to avoid approving every `exec` and `write` during setup.
</Tip>

### Optional: stdio smoke test

For a terminal-only check without an agent UI, pipe MCP over stdio from the project directory:

```bash
# From another terminal while ok start is running (or for server-free exec)
cd my-knowledge-base
ok mcp
```

The E2E harness expects `tools/list` to include `exec`, `search`, `write`, and `edit`, and verifies `exec` read-back after a `write` round-trip.

## First agent-driven edit

After MCP verification, ask the agent to create initial content:

```
Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts.
```

Writes appear live in the editor through Yjs CRDT sync. The agent icon in the editor chrome shows activity across files once writes begin.

## Troubleshooting

<AccordionGroup>

<Accordion title="ok start says the directory is not set up">
Run `ok init` in the project root (the directory that should contain `.ok/`), then retry `ok start`.
</Accordion>

<Accordion title="Server already running or lock collision">
Check `ok status`. Stop the existing instance with `ok stop`, or use `--cwd` to point at a different project. For stale lock files after a crash, run `ok clean` (never touches live servers).
</Accordion>

<Accordion title="Git errors on init or start">
`ok init` requires git to initialize a parent repository. Install git or run `git init` yourself, then re-run `ok init`. `ok start` exits with code `78` when git is missing or too old for server features.
</Accordion>

<Accordion title="Agent does not call exec">
Restart the agent so it reloads MCP config written by `ok init`. Run `ok repair-skills` or restart with `ok start` (which re-runs skill and MCP repair sweeps). See [Wire agent editors](/wire-agent-editors) for per-editor paths and manual registration.
</Accordion>

<Accordion title="Writes fail with server not running">
Start the collaboration server with `ok start` (or let MCP auto-start it on the first write). Read-only `exec` works without the server; `write` and `edit` do not.
</Accordion>

</AccordionGroup>

## Related pages

<CardGroup>

<Card title="Installation" href="/installation">
Node.js 24+, git, npm CLI install, and macOS desktop DMG paths.
</Card>

<Card title="Initialize a project" href="/initialize-project">
Full `ok init` semantics: config scopes, sharing modes, and MCP registration details.
</Card>

<Card title="Wire agent editors" href="/wire-agent-editors">
Per-editor MCP paths, `ok repair-skills`, and verification prompts.
</Card>

<Card title="Collaboration server" href="/collaboration-server">
Hocuspocus lifecycle, locks, idle shutdown, and server-free vs server-routed tools.
</Card>

<Card title="MCP tools reference" href="/mcp-tools-reference">
All 17 tools, input nesting, preview envelopes, and conflict guards.
</Card>

<Card title="Troubleshooting" href="/troubleshooting">
`ok diagnose health`, `ok clean`, and bug-report bundles.
</Card>

</CardGroup>