Getting Started

1. Launch Kaimon

After installing via ]app add (see Installation), run:

kaimon

On the first run, Kaimon installs dependencies, precompiles, then launches the setup wizard — an interactive TUI that walks you through security mode, API key generation, and port selection:

Once setup completes, the dashboard opens:

The dashboard shows connected REPL sessions, live tool call activity, server logs, search index status, and configuration — all from one place.

Launch options

kaimon --port 3000       # custom port
kaimon --theme esper     # theme: kokaku, esper, motoko, neuromancer
kaimon --revise          # load Revise for live code reloading

2. Connect an MCP Client

Press c in the dashboard to open the Config tab. From there you can generate and write MCP configuration for your editor with a single keypress — no manual file editing needed.

Supported clients: Claude Code, VS Code (Copilot/Continue), Cursor, Gemini CLI, Antigravity, OpenCode, and KiloCode. The Config tab writes the correct config format for each one, including your API key if running in authenticated mode.

3. Connect External REPLs

The Gate lets any Julia REPL register itself as a live session. Kaimon discovers it automatically and shows it in the Sessions tab. There are three ways to connect:

Option A — Manual (one-off)

Add the lightweight gate package to your project and call serve() in any running REPL:

]add KaimonGate
using KaimonGate
KaimonGate.serve()

This is non-blocking. The gate runs in the background and the REPL stays interactive. Good for trying things out or for REPLs you start manually.

Option B — Per-project auto-connect

A .julia-startup.jl file in a project connects only the REPLs you start with it. Kaimon can write the file, plus an executable repl launcher that loads it:

using Kaimon
Kaimon.Generate.create_startup_script("/path/to/MyProject")   # writes .julia-startup.jl
Kaimon.Generate.create_repl_script("/path/to/MyProject")      # writes ./repl

The file contains:

# Kaimon Gate — auto-connect this REPL to the Kaimon dashboard.
# Uses the lightweight KaimonGate package. Activates only when KaimonGate is
# available in this environment, so other Julia versions or clean envs start
# silently — no warnings in sessions that don't have it.
if Base.identify_package("KaimonGate") !== nothing
    try
        @eval using Revise
    catch
    end
    try
        @eval using KaimonGate
        @eval KaimonGate.serve()
    catch e
        @warn "KaimonGate failed to start" exception = e
    end
end
# Kaimon Gate — end

Start Julia through ./repl, or load the file yourself with --load=:

julia --project --load=.julia-startup.jl

Startup succeeds normally when Kaimon isn't running or KaimonGate isn't installed.

Option C — Global auto-connect (every Julia session)

The Config tab's "Julia startup.jl (global gate)" option appends the same Gate snippet to ~/.julia/config/startup.jl. After that, every Julia session on your machine auto-connects without any per-project setup:

Config tab → g

It is also listed as "Julia startup.jl (global gate)" under i (client list).

This is the lowest-friction option: start any Julia REPL and it appears in Kaimon's Sessions tab within a second or two.

What does this startup file do? It loads Revise so hot-reloading works automatically in every session.

It then calls KaimonGate.serve() to register the REPL with Kaimon. This uses the lightweight KaimonGate package (ZMQ + stdlib only), installed once into your global environment, so every session can connect without pulling in the full Kaimon dependency tree.

Both are wrapped in try/catch so Julia starts normally even if KaimonGate isn't installed or the server isn't running. :::

Upgrading from an older setup

If you previously connected via the full Kaimon package (a using Kaimon; Gate.serve() snippet), the kaimon CLI offers a one-time opt-in update on startup that installs the lightweight KaimonGate globally, removes the heavyweight Kaimon from your global environment, and migrates your startup.jl snippet to the form above.

Custom tools

REPLs can also expose custom tools that the AI agent can call — the Gate reflects on your function signatures to generate MCP schemas automatically:

"""Return summary statistics for a dataset."""
function summarize(path::String, max_rows::Int=1000)
    # your domain logic
end

KaimonGate.serve(tools=[KaimonGate.GateTool("summarize", summarize)])

See The Gate for the full custom tools guide.

4. Semantic Search

The Search tab connects to a local Qdrant instance and manages vector indexes over your codebase. Once indexed, your AI agent can search with natural language using the search_code tool.

Navigate to the Search tab (press 4), select a collection, and run a query. Kaimon chunks your source files, embeds them with a local Ollama model, and stores the vectors in Qdrant — all from the TUI.

Requirements: Qdrant and Ollama running locally. See Semantic Search for setup and configuration.

Next Steps

• Tool Catalog — all available tools and their parameters

• The Gate — connecting external processes and building custom tools

• Architecture — how the components fit together

• Configuration — security, preferences, and config files