Terminal

The terminal is Omnigent's default interface: keyboard-first, with streaming output and real-time tool execution. If you already live in a terminal, this is the fastest way to work with your agent.

Every interface (terminal, web UI, mobile, and desktop) connects to the same persistent, shareable session, so you can start work in one place and keep going anywhere.

Start a session

The terminal interface requires tmux, so install it first if you don't have it:

# macOS
brew install tmux

# Debian / Ubuntu
apt install tmux

Then launch an agent:

omni claude                          # Claude Code
omni codex                           # Codex
omni goose                           # Goose (native TUI)
omni hermes                          # Hermes (native TUI)
omni run agent.yaml                  # custom omnigent
omni run ./my-agent/                 # directory with config.yaml

omni claude, omni codex, omni goose, and omni hermes launch a built-in coding agent with Omnigent's UI. No YAML needed. See the Coding Agent tutorial and the full harness list in Harnesses.

omni run starts a custom omnigent from a YAML config. See Custom Agents for how to write one.

A bare omni with no arguments does not launch an agent. On an interactive terminal it starts the local server / host in the background and returns; to launch an agent, name it (omni polly, omni claude, …) or use omni run. In a non-interactive shell (a pipe or CI, with no TTY), bare omni prints --help instead of blocking on a sign-in prompt.

CLI overrides

Override executor values at runtime without editing the YAML:

omni run agent.yaml --harness codex --model gpt-4.1-mini

The --harness and --model flags map directly to the executor block. This lets you reuse the same config across different LLM backends.

From here, the agent streams its output as it thinks and acts. Tool calls run in real time, so you watch file writes, shell commands, and API calls land as they happen. The session also stays in sync with the Web UI both ways: run the agent in your terminal and glance at the browser whenever you want file diffs or inline comments.

Sessions and conversations

A session is a conversation. Every message, tool call, and file change lives in one continuous thread. Sessions are the core unit of work in Omnigent, and three properties make them useful:

• Agent-independent. A session belongs to you, not to a specific agent. Switch agents mid-conversation: start with a planner, switch to a coder, bring in a reviewer. The full history carries forward.
• Persistent. Every session has a conversation ID and lives beyond the current terminal window. Close your laptop, come back tomorrow, resume where you left off: omni resume <conversation_id>
• Shared. Any omnigent can read the history of other sessions you have access to. When you spin up a new task, the agent already has context from previous work.

Customize automatic session titles

New sessions get an automatic title generated from your first message, so your session list stays readable without manual naming. You can steer the style or format of those titles with natural-language guidance in your Omnigent config:

omni config set --global \
  'session_title_instructions=Prefix titles with the current date as lowercase mon-dd. Use PR-number-short-name for pull requests, issue-number-short-description for issues, and a short snake_case activity otherwise.'

The isolated title generator receives the current date (as YYYY-MM-DD) and then applies your requirements to the first user message. Generated titles longer than 60 characters are rejected, leaving the first-message fallback title in place.

session_title_instructions is server-owned metadata configuration, not part of an agent's portable instructions, so it must be set with --global. Setting it as a project-local key (.omnigent/config.yaml) is rejected, and omni config list flags any project-local value as an ignored user-level-only setting. The setting takes effect for new sessions after the local Omnigent server restarts.

For longer instructions, edit ~/.omnigent/config.yaml directly and use a YAML block scalar:

session_title_instructions: |
  Prefix every title with the current date as lowercase mon-dd.
  For pull requests use mon-dd-PR-number-short-name.
  For issues use mon-dd-issue-number-short-description.
  For other work use mon-dd-short_snake_case_activity.

When to use the terminal

The terminal shines when you want to stay close to the command line:

• Fast iteration. Keyboard-first, no context switching to a browser.
• SSH environments. Works over SSH where a browser isn't available.
• Low-bandwidth connections. Text-only, minimal overhead.
• Scripting and automation. Composable with other CLI tools.