API Reference

Public API

Kaimon.start! Function

start!(; port=nothing, verbose=true, security_mode=nothing, julia_session_name="", workspace_dir=pwd())

Start the Kaimon MCP server.

Arguments

• port::Union{Int,Nothing}=nothing: Server port. Use 0 for dynamic port assignment (finds first available port in 40000-49999). If nothing, uses port from configuration.

• verbose::Bool=true: Show startup messages

• security_mode::Union{Symbol,Nothing}=nothing: Override security mode (:strict, :relaxed, or :lax)

• julia_session_name::String="": Name for this Julia session

• workspace_dir::String=pwd(): Project root directory

Dynamic Port Assignment

Set port=0 (or use "port": 0 in config.json) to automatically find and use an available port. The server will search ports 40000-49999 for the first free port. This higher range avoids conflicts with common services.

Examples

# Use configured port from config.json
Kaimon.start!()

# Use specific port
Kaimon.start!(port=4000)

# Use dynamic port assignment
Kaimon.start!(port=0)

# Start with a custom name
Kaimon.start!(julia_session_name="data-processor")

Kaimon.tui Function

tui(; port=2828, theme=:kokaku)

Launch the Kaimon TUI. This is a blocking call that takes over the terminal.

Starts the MCP HTTP server in a background task and watches for REPL gate connections in ~/.cache/kaimon/sock/.

Arguments

• port::Int=2828: Port for the MCP HTTP server

• theme::Symbol=:kokaku: Tachikoma theme name

Kaimon.call_tool Function

call_tool(tool_id::Symbol, args::Dict)

Call an MCP tool directly from the REPL without hanging.

This helper function handles the two-parameter signature that most tools expect (args and stream_channel), making it easier to call tools programmatically.

Examples

Kaimon.call_tool(:exec_repl, Dict("expression" => "2 + 2"))
Kaimon.call_tool(:investigate_environment, Dict())
Kaimon.call_tool(:search_methods, Dict("query" => "println"))

Available Tools

Call list_tools() to see all available tools and their descriptions.

Kaimon.list_tools Function

list_tools()

List all available MCP tools with their names and descriptions.

Returns a dictionary mapping tool names to their descriptions.

Kaimon.tool_help Function

tool_help(tool_id::Symbol)

Get detailed help/documentation for a specific MCP tool.

Kaimon.security_status Function

security_status()

Display current security configuration.

Kaimon.setup_security Function

setup_security(; force::Bool=false)

Launch the security setup wizard.

Kaimon.generate_key Function

generate_key()

Generate and add a new API key to the global configuration.

Kaimon.revoke_key Function

revoke_key(key::String)

Revoke (remove) an API key from the global configuration.

Kaimon.allow_ip Function

allow_ip(ip::String)

Add an IP address to the global allowlist.

Kaimon.deny_ip Function

deny_ip(ip::String)

Remove an IP address from the global allowlist.

Kaimon.set_security_mode Function

set_security_mode(mode::Symbol)

Change the security mode (:strict, :relaxed, or :lax) in the global configuration.

Gate Module

Missing docstring.

Missing docstring for Kaimon.Gate. Check Documenter's build log for details.

Kaimon.Gate.GateTool Type

GateTool(name, handler)

A tool declared by a gate session. The handler is a normal Julia function; the gate infrastructure reflects on its signature to generate MCP schema and reconstructs typed arguments from incoming Dict values.

Example

function send_key(key::String, modifier::Symbol=:none)
    # handle key event
end

Gate.serve(tools=[GateTool("send_key", send_key)])

Kaimon.Gate.serve Function

serve(; session_id=nothing, force=false, tools=GateTool[], namespace="", allow_mirror=true, allow_restart=true)

Start the eval gate. Binds a ZMQ REP socket on an IPC endpoint and listens for eval requests from the Kaimon TUI server.

Non-blocking — returns immediately. The gate runs in a background task. The session name is derived automatically from the active project path.

Skips registration for non-interactive processes (no TTY). Use force=true to override the TTY check.

Arguments

• session_id::Union{String,Nothing}: Reuse a session ID (e.g. after exec restart)

• force::Bool: Skip the TTY gate (for non-interactive processes that want a gate)

• tools::Vector{GateTool}: Session-scoped tools to expose via MCP

• namespace::String: Stable prefix for tool names. Auto-derived from project basename if empty. Use explicit namespaces for multi-instance workflows:

  serve(tools=tools, namespace="todo_dev")    # branch A
  serve(tools=tools, namespace="todo_main")   # branch B

• mode::Symbol: Transport mode — :ipc (default, local Unix socket) or :tcp (network-accessible, for remote debugging).

• host::String: Bind address for TCP mode (default "127.0.0.1", localhost only). Use "0.0.0.0" to accept connections from remote machines (no auth — use with care).

• port::Int: Port for TCP mode (default 0 = ephemeral, ZMQ picks a free port). Both REP and PUB sockets support this. Use a fixed port for predictable endpoints.

Example

using Kaimon
Gate.serve()

# With custom tools
Gate.serve(tools=[GateTool("send_key", my_key_handler)])

# TCP mode for remote debugging (e.g. from a model server)
Gate.serve(mode=:tcp, port=9876, force=true)

Environment variables

These override the keyword defaults when set:

• KAIMON_GATE_MODE: "ipc" or "tcp" (default: "ipc")

• KAIMON_GATE_HOST: Bind address for TCP (default: "127.0.0.1")

• KAIMON_GATE_PORT: Port for TCP (default: "0" = ephemeral)

• KAIMON_GATE_STREAM_PORT: PUB stream port for TCP (default: "0" = ephemeral). Use a fixed port when tunneling so the client can connect to a known port.