Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

A session is the live context for one agent run in Omnigent. It holds the full conversation history — messages, sub-agent invocations, terminal resources, and produced files — and persists on the server database so it can be resumed, shared, or forked from any device. Sessions are identified by a stable conv_* ID and are bound to the runner that created them; when a teammate attaches or the web UI connects, they all read from the same live session on the server.

​
Starting a Session

Run a named harness directly. Omnigent resolves the configured credential and starts a session in your terminal:
omnigent claude          # Claude Code via claude-sdk harness
omnigent codex           # OpenAI Codex harness
omnigent run examples/polly/   # a YAML-defined agent
A local server starts automatically in the background (if not already running) and the web UI becomes available at http://localhost:6767.

​
Session States

A session moves through the following lifecycle states:
StateMeaning
idleThe session exists and is ready, but no agent turn is currently running.
runningAn agent turn is in progress — the runner is executing the LLM loop.
failedThe most recently completed task ended with an error. Check last_task_error for details.
Paused (elicitation)A policy has paused the session and is waiting for your approval before the agent proceeds. The session shows a pending elicitation badge in the web UI.
Sessions move back to idle after each completed turn, allowing further interaction. An agent run is paused — not stopped — when a policy fires an elicitation; the agent resumes as soon as you respond.

​
What a Session Contains

Every session holds several kinds of associated resources:

Messages and comments

The full conversation history: user messages, assistant turns, tool call results, and inline comments posted by teammates during a shared session.

Sub-agent child sessions

When a supervisor agent delegates work to sub-agents, each sub-agent runs in its own child session. The parent session tracks all child sessions and their statuses.

Terminal resources

Native harness sessions (claude-native, codex-native) attach a live tmux terminal to the session. The web UI and CLI can attach to the same terminal.

File resources

Files produced by the agent (code files, data exports, etc.) are stored as artifacts on the server and accessible via the web UI or the files API.
A session snapshot from the Python SDK includes all of these fields: 
session.id                  # "conv_abc123"
session.status              # "idle" | "running" | "failed"
session.agent_name          # "polly"
session.harness             # "claude-sdk"
session.title               # human-readable title (set by agent or user)
session.items               # committed conversation items (list of dicts)
session.runner_id           # runner currently bound to this session
session.last_total_tokens   # token count from the most recent completed task
session.last_task_error     # error details if the most recent task failed

​
Attaching to a Session

Any team member with access to the server can attach to a live session and co-drive it: 
omnigent attach conv_abc123
omnigent attach conv_abc123 --server https://your-host
attach is a thin client — it joins the already-running conversation without spawning a new server or runner. Messages you type are dispatched to the runner that owns the session (typically your teammate’s machine), which means the agent runs with that machine’s credentials and filesystem access. Use this for pair-programming on an agent, or to hand control to a domain expert mid-investigation.
attach never starts a server or runner. If there is no live session at the given ID, it fails loudly. Use omnigent run to start a new session, or omnigent resume to restart a stored one.
You can also share a session’s URL from the web UI. Teammates open the link, watch the agent work in real time, and can post messages without any CLI setup.

​
Forking a Session

Forking creates an independent copy of a session starting from its current history (or from a specific response within it). The fork gets a new session ID and runs on its own runner: 
omnigent run --fork conv_abc123
This is useful when you want to explore a different direction from a shared conversation without affecting the original, or when a teammate wants to continue investigating independently from a fork point. The Python SDK also exposes forking directly: 
forked = await client.sessions.fork("conv_abc123", title="My fork")

​
Streaming Session Events

All session output is delivered as a real-time SSE stream on GET /v1/sessions/{id}/stream. The Python SDK wraps this via SessionsNamespace.stream(): 
async for event in client.sessions.stream("conv_abc123"):
    print(event)
For the higher-level Session helper (the client.session(model=...) API), use session.query() which buffers the stream into a convenient result or chunk iterator: 
from omnigent_client import OmnigentClient
import asyncio

async def main():
    async with OmnigentClient(base_url="http://localhost:6767") as client:
        session = client.session(model="claude")
        async for chunk in await session.query("Summarize the current directory", stream=True):
            print(chunk, end="", flush=True)

asyncio.run(main())
session.query() with stream=True returns a QueryStream that yields text chunks as they arrive. With stream=False (the default) it collects the full response and returns a QueryResult with .text and any .files the agent produced.
Sessions are persisted in the server database — SQLite for single-instance or demo deploys, Postgres for production. The database backend is configured via the DATABASE_URL environment variable. Sessions survive server restarts and are resumable from any device.

Build docs developers (and LLMs) love

Get started for freeTalk to us