Skip to content
Koma

sessions:manage

List takes no fields. Each row has id, name, workdir, live, and working. The list is a point in time. It does not subscribe, and it does not poll other daemons.

{ "method": "sessions.list", "params": {} }

Create takes an optional workdir and an optional name. workdir must be an absolute path that exists, or leave it out to use the daemon launch directory. Success is an id. A failed rename is retried once and does not fail the create.

{
  "method": "sessions.create",
  "params": { "workdir": "/absolute/existing/path", "name": "launch notes" }
}

Switch takes a session uuid. A session in this daemon returns delivery local. A session in another daemon returns delivery signaled. Signaled means a client still has to attach. The terminal may ignore that signal. A missing session is an error.

{ "method": "sessions.switch", "params": { "session": "sess-uuid" } }

Spawn into takes a session and a task, plus the same optional fields as agents.spawn. On the local daemon the result matches agents.spawn and the agent is tracked. Across processes the result is status sent and the session id, with no agent id. workspace is honored only on the local branch. A cross-daemon workspace is ignored. A down target returns the text: session not live.

{
  "method": "sessions.spawn_into",
  "params": {
    "session": "sess-uuid",
    "task": "Draft the reply."
  }
}
fn drive(koma: &mut Koma) {
    let sessions = koma.call("sessions.list", serde_json::json!({}));
    let first = sessions.as_array().and_then(|rows| rows.first()).cloned();
    let Some(row) = first else { return };
    let id = row.get("id").and_then(|v| v.as_str()).unwrap_or("");
 
    let created = koma.call(
        "sessions.create",
        serde_json::json!({ "name": "launch notes" }),
    );
    println!("created {}", created.get("id").and_then(|v| v.as_str()).unwrap_or(""));
 
    let switched = koma.call("sessions.switch", serde_json::json!({ "session": id }));
    println!("delivery {}", switched.get("delivery").and_then(|v| v.as_str()).unwrap_or(""));
 
    let spawned = koma.call(
        "sessions.spawn_into",
        serde_json::json!({ "session": id, "task": "Draft the reply." }),
    );
    println!("{spawned}");
}