Programmatic Usage

Install either the full omnigent Python package or just omnigent-client for the SDK. Both provide the omnigent_client import used below. Use a package version matching your server version.

From your repository, run an agent with -p to send a prompt, print its response, and exit. Use your agent directory or YAML file in place of ./my-agent/:

omni run ./my-agent/ -p "Review the changes in the latest commit"

Omnigent starts a local server and runner automatically. Sessions are saved by default; their URL appears on stderr when they start. Open it to follow progress in the Web UI:

Omnigent session: http://127.0.0.1:6767/c/conv_abc123

Common options:

These examples use an agent YAML or directory through omni run; native terminal harnesses have their own CLI behavior. To run tools on another machine or in a cloud sandbox, use the REST API's host options.

This example creates a native Claude Code session on an existing server. You'll need a connected runner configured with your repository, credentials, and tools.

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(
        base_url="http://127.0.0.1:6767",
        # For a server requiring a bearer token:
        # headers={"Authorization": "Bearer <access_token>"},
    ) as client:
        agent = await client.sessions.resolve_agent("claude-native-ui")
        runner_id = await client.sessions.resolve_online_runner(harness=agent.harness)
        if runner_id is None:
            raise RuntimeError("Connect a runner that supports native Claude Code first")
 
        session = await client.sessions.create_from_agent_id(agent.id, title="Code review")
        await client.sessions.bind_runner(session.id, runner_id=runner_id)
        print(session.id)
        print(f"http://127.0.0.1:6767/c/{session.id}")
 
asyncio.run(main())

Use the printed session ID to send a message in the next step, or open the URL to view the session.

Create a native Claude Code session with curl and jq. Connect the machine containing your repository and keep this command running while you use the session:

omni host --server http://127.0.0.1:6767

For shared servers, include your authentication credentials in each request, such as -H "Authorization: Bearer $ACCESS_TOKEN".

curl -fsS http://127.0.0.1:6767/v1/agents \
  | jq -r '.data[] | select(.harness == "claude-native") | .id'

curl -fsS http://127.0.0.1:6767/v1/hosts \
  | jq '.hosts[] | {name, host_id}'

curl -fsS http://127.0.0.1:6767/v1/hosts \
  | jq -r '.hosts[] | select(.name == "<host-name>") | .host_id'

SESSION_ID=$(curl --fail-with-body http://127.0.0.1:6767/v1/sessions \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "ag_reviewer",
    "host_id": "host_example",
    "workspace": "/home/ci/my-repository",
    "title": "Review latest commit"
  }' | jq -er '.id')

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" | jq

Use --continue (or -c) to send a follow-up prompt to the most recent conversation for the same agent:

omni run ./my-agent/ --continue -p "Now check whether the tests cover those changes"

To continue a specific conversation, use its ID:

omni run ./my-agent/ --resume "<conversation_id>" -p "Explain the first finding"

Use --resume when your automation runs multiple conversations and needs to target a specific one. Use the ID from the CLI's session URL, or look it up with GET /v1/sessions.

This example sends a message to an existing session. Replace conv_abc123 with its ID. The session must have an online runner with access to the repository, model credentials, and tools. The SDK does not start a runner for you.

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(base_url="http://127.0.0.1:6767") as client:
        await client.sessions.post_event("conv_abc123", {
            "type": "message",
            "data": {
                "role": "user",
                "content": [{"type": "input_text", "text": "tell me a joke"}],
            },
        })
 
asyncio.run(main())

The call returns when the server accepts the message; it does not wait for the agent's reply. Open the session in the Web UI to follow its progress.

Send the first prompt or a follow-up to the same session:

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/events" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "message",
    "data": {
      "role": "user",
      "content": [{"type": "input_text", "text": "Review the changes in the latest commit"}]
    }
  }'

The request returns when the server accepts the message, without waiting for the reply. Print the URL to follow the review:

echo "http://127.0.0.1:6767/c/$SESSION_ID"

The CLI prints the session URL to stderr at startup and the collected assistant text to stdout when the run finishes. Open that URL to see the conversation and its progress.

Use the Python or REST tab to list saved sessions, retrieve history, or monitor an agent from your application.

List recent sessions, then read a session's status and messages. Replace conv_abc123 with the ID you want to inspect.

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(base_url="http://127.0.0.1:6767") as client:
        sessions = await client.sessions.list(limit=20, sort_by="updated_at")
        for session in sessions:
            print(session.id, session.title, session.status)
        session_id = "conv_abc123"
        session = await client.sessions.get(session_id)
        print(session.status)
        print(await client.sessions.list_items(session_id))
 
asyncio.run(main())

For live events, iterate over client.sessions.stream(session_id). Use session.status to check the session itself and await client.sessions.subtree_busy(session_id) to check whether any of its descendants are busy.

History is paginated. Use the last item's id as after in the next list_items call to read further. Live events do not replay history; retrieve the snapshot and history again after reconnecting.

List sessions on a local single-user server:

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions?limit=20&sort_by=updated_at"

Filter by agent_name, agent_id, or search_query. Listings exclude archived sessions and child sessions by default; use include_archived=true or kind=any when you need them. Both session and history listings are paginated: when has_more is true, use the returned last_id as the next request's after cursor.

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/<session_id>/items"

The SSE stream supplies live updates; it does not replay conversation history. Use the session snapshot and /items to recover state after reconnecting.

To fork into an interactive session:

omni run ./my-agent/ --fork "<conversation_id>"

--fork cannot be combined with -p. For scripted forks, archiving, or cancellation, use the Python or REST tab.

These calls run inside the same async with OmnigentClient(...) as client block used above. Replace session_id with the session you want to manage.

A fork's new ID is fork["id"]. Bind a runner before sending it a prompt:

await client.sessions.bind_runner(fork["id"], runner_id=runner_id)

Forking copies the full history by default. Pass up_to_response_id to fork from an earlier response. Use the REST tab to permanently delete a session and its resources.

Use the SESSION_ID from the earlier examples.

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/events" \
  -H 'Content-Type: application/json' \
  -d '{"type": "interrupt"}'

FORK_ID=$(curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/fork" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Explore another approach"}' | jq -er '.id')

curl --fail-with-body -X PATCH "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"archived": true}' | jq

curl --fail-with-body -X PATCH "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"archived": false}' | jq

curl --fail-with-body -X DELETE "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" | jq