Session Management

Kaimon connects AI agents to live Julia REPLs. Each connected REPL is a session – an independent Julia process with its own state, loaded packages, and working directory. Agents execute code, inspect types, run tests, and more by routing requests to a specific session.

What Is a Session?

A session represents a single Julia REPL that has connected to the Kaimon server. Each session has:

• A unique 8-character session key (e.g., a3f8b2c1) used to identify and target it.

• Its own Julia process with independent module state, variables, and loaded packages.

• A health status indicating whether it is responsive.

Multiple sessions can be connected simultaneously, allowing agents to work across different projects or environments at the same time.

Starting a Session

There are three ways to connect a REPL, ranging from manual to fully automatic.

Manual

Call Gate.serve() in any running REPL:

using Kaimon
Gate.serve()

This is non-blocking — the gate runs in a background task and the REPL remains interactive. Good for one-off connections or scripts.

Per-project auto-connect

The Config tab's onboarding flow writes a .julia-startup.jl file into your project directory. Load it with Julia's --load= flag and the REPL auto-connects whenever it launches in that directory:

julia --load=.julia-startup.jl

The generated file loads Revise and calls Gate.serve(), both wrapped in try/catch so startup succeeds even when Kaimon is not running:

# .julia-startup.jl
try
    using Revise
catch e
    @info "ℹ Revise not loaded (optional)"
end
try
    using Kaimon
    Gate.serve()
catch e
    @warn "Kaimon Gate failed to start" exception = e
end

Global auto-connect

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

Each REPL that calls Gate.serve() registers as a separate session with its own session key.

Managed sessions

The start_session MCP tool spawns Julia processes for projects in the allowed-projects list. This lets AI agents autonomously start sessions for projects they need to work on.

start_session(project_path="/path/to/MyProject")
# => "Session started. Session key: a3f8b2c1"

start_session()
# => Lists all allowed projects and their status

When a managed session starts, Kaimon:

1. Spawns a Julia subprocess via PTY (pseudo-terminal).

2. Activates the project environment and runs Pkg.instantiate.

3. Loads Revise and calls Gate.serve(spawned_by="agent").

4. Waits up to 120 seconds for the gate connection.

The spawned process connects back as a regular gate session. It appears in the Sessions tab like any other session, but is tagged with spawned_by: agent to distinguish it from manually started REPLs.

To configure which projects can be spawned, see Projects Configuration.

Session Routing

When only one session is connected, agents do not need to specify a target – all requests are routed to the single active session automatically.

When multiple sessions are connected, agents must specify which session to target by providing the 8-character session key. Every tool that executes code or inspects state accepts a session (or ses) parameter for this purpose:

ex(e="using LinearAlgebra", ses="a3f8b2c1")
run_tests(session="a3f8b2c1")
type_info(type_expr="Matrix{Float64}", session="a3f8b2c1")

If an agent omits the session key when multiple sessions are connected, the server returns an error indicating that a session must be specified.

Viewing Sessions in the TUI

The TUI (terminal user interface) includes a Sessions tab that displays all connected REPLs. For each session, it shows:

• The session key.

• Connection status and health (based on periodic heartbeat checks).

• The Julia version and active project environment.

This tab provides a real-time overview of which REPLs are available for agents to target.

Session terminal

For agent-spawned sessions, you can open an embedded terminal by selecting the session and pressing Enter. This opens a full-screen PTY console connected to the session's Julia REPL, allowing you to interact with it directly while the agent continues to work through MCP tools.

Press Esc to close the terminal overlay. The underlying Julia process and gate connection remain active — closing the terminal only dismisses the view.

Key reference

Key	Action
↑ / ↓	Navigate session list
Enter	Open terminal for agent-spawned session
f	Filter sessions
Esc	Close terminal or filter

Restarting a Session

There are three ways to restart a session:

From the agent — use the manage_repl tool:

manage_repl(command="restart")
manage_repl(command="restart", session="a3f8b2c1")

From the REPL — call Gate.restart() directly:

Gate.restart()

From the TUI — press r on the selected session in the Sessions tab.

All three methods use execvp, which swaps the running process image without spawning a child. This means:

• The process ID stays the same.

• All Julia state is cleared (a fresh session begins).

• The session key is preserved, so agents can continue targeting the same key.

• Revise and other packages are reloaded from scratch.

Use restart when Revise fails to pick up structural changes, or when the session state has become corrupted.

Shutting Down a Session

To cleanly disconnect a session, use the manage_repl tool with the shutdown command:

manage_repl(command="shutdown")
manage_repl(command="shutdown", session="a3f8b2c1")

This stops the session permanently. The session key is deregistered, and the REPL disconnects from the server. The Julia process exits.

Auto-Discovery

Kaimon uses a file-based discovery mechanism. When a REPL calls Gate.serve(), it writes a ZMQ socket file to:

~/.cache/kaimon/sock/

The Kaimon server watches this directory for new socket files. When a new file appears, the server automatically connects to the corresponding REPL and registers it as a session. When a socket file is removed (e.g., on shutdown), the session is deregistered.

This design means sessions can start and stop independently of the server – the server discovers them as they appear.

Session Preferences

Per-project session preferences can be configured in ~/.config/kaimon/projects.json under the session_prefs key. Preferences are matched by project name (case-insensitive basename) or full path, with a * wildcard for global defaults:

{
  "session_prefs": {
    "MyProject": {
      "mirror_repl": true,
      "allow_restart": false
    },
    "*": {
      "allow_restart": true
    }
  }
}

Preference	Description
mirror_repl	Mirror agent eval output into the host REPL. Useful for seeing what agents execute in real time.
allow_restart	Whether the manage_repl(command="restart") command is permitted for this session.

See Configuration for the full projects.json format.