Agentics CLI

Voice-reactive terminal Orb with a dynamic powerboard, realtime streaming, sub-agent rendering, image generation, and direct desktop tool access. The whole Agentics surface, in a single terminal binary.

  ▄▀▀▀▀▀▄ ▄▀▀▀▀▀▀  █▀▀▀▀▀▀ █▀▄   █ ▀▀▀█▀▀▀ ▀▀▀█▀▀▀ ▄▀▀▀▀▀▀ ▄▀▀▀▀▀▀ ™
  █▀▀▀▀▀█ █    ▀█▀ █▀▀▀▀▀  █  ▀▄ █    █       █    █        ▀▀▀▀▀▄
  ▀     ▀  ▀▀▀▀▀▀  ▀▀▀▀▀▀▀ ▀    ▀▀    ▀    ▀▀▀▀▀▀▀  ▀▀▀▀▀▀ ▀▀▀▀▀▀

What it is

A first-class Agentics surface that runs entirely inside your terminal. It hosts the same particle Orb that lives on phone, watch, and desktop wallpaper, talks to the realtime API over a WebSocket, renders structured artefacts into a self-organising powerboard, and exposes the user's local filesystem and shell to the agent through real function tools.

Speak to it, type to it, watch it work.

Features

• Particle Orb with voice reactivity, audio-level driven motion, idle / listening / thinking / speaking states.
• Powerboard with dynamic auto-layout. Up to eight visible boxes at once. Boxes beyond the cap are hidden, not destroyed, and surface in a hidden-count badge.
• Pinned and priority-aware allocation. Pinned boxes (Primary Agent terminal, active sub-agents) never get evicted by new renders.
• Real sub-agent spawning. deploy_agent triggers a backend job and a live agent box that streams the job's progress, tool calls, and output.
• Direct desktop tool access. write_file, read_file, run_command, list_dir work against the user's local disk and stream output back into a box.
• Image generation through AgenPics and other supported families. Canonical ratios map to API dimensions automatically.
• Authentication baked in. Email / password login and signup screens, saved sessions in ~/.agentics/auth.json, automatic re-auth.
• Companion device registration. The CLI registers itself as a desktop companion every session so other Agentics surfaces (mobile app, browser extension, watch app, Console) see it as online.
• Built-in chat input with vim-style normal mode, history, undo, registers, and word-wise motions.

Install

agpk install -g .

Or run directly:

node ./dist/cli.js

agpk is the Agentics package manager. Use it for everything in this project; npm is intentionally avoided.

The Linux and Windows binaries are self-contained and require no Node runtime.

Usage

agentics [options]

| Flag | Description | | ---- | ----------- | | --token <key> | API key. Falls back to AGENTICS_API_KEY or AGENTICS_TOKEN. | | --model <name> | Realtime model id (default AgentX). | | --voice <name> | TTS voice id (default female2). | | --api-base <url> | Override the API base URL. | | --preset <name> | Apply a powerboard preset on launch. | | --no-mic | Disable microphone capture. | | --no-realtime | Run without connecting to the realtime API. | | --no-banner | Hide the Agentics banner. | | --silence <ms> | Server VAD silence threshold (default 1600). | | --threshold <float> | Server VAD energy threshold (default 0.6). | | --debug | Print tool and event traffic to stderr. | | --list-presets | List preset names and exit. | | --help, -h | Show CLI help. |

Environment

| Variable | Purpose | | -------- | ------- | | AGENTICS_API_KEY | Realtime API token (also accepts AGENTICS_TOKEN). |

Keyboard

| Key | Action | | --- | ------ | | i | Open chat input in insert mode. | | Esc | Leave insert mode, then hide chat input. | | Tab | Cycle focus between menu, orb, chat input, and visible boxes. | | m | Toggle the side menu. | | v | Toggle the microphone. | | b | Toggle the header banner. | | c | Clear the powerboard. | | f | Recenter the orb. | | 1 | Particles orb mode. | | 3 | Flow orb mode. | | q | Quit. | | Ctrl+C | Quit. Inside chat input, the first press clears the line; a second press within two seconds quits. |

Inside chat input, full vim normal mode is available with h j k l w b e 0 ^ $ x X i a A I o O p P u ~ d y c D C Y and the dd / yy / cc doubles.

Realtime tools

The realtime session exposes these function tools to the model. Connor never invokes them directly; the model decides.

| Tool | Effect | | ---- | ------ | | render_box | Add a new box to the powerboard. Auto-laid out. | | update_box | Update an existing box content or title. | | remove_box | Delete a box. | | hide_box | Hide a box (kept in memory, counter overlay shows hidden count). Pinned boxes are protected. | | restore_hidden | Restore one or all hidden boxes. Respects the visible cap. | | clear_board | Wipe all boxes and return to full-screen orb. | | resize_orb | Scale the orb from 0.2x to 3.0x. | | deploy_agent | Spawn a real backend sub-agent. A pinned agent box appears immediately and streams the job. | | write_file | Write a file to the user's local disk and render the result. | | read_file | Read a local file and render its content. | | run_command | Spawn a shell command, stream stdout into a live box, return exit code and captured output. | | list_dir | List a directory and render as a list box. | | render_html | Render an HTML payload reduced to ANSI text. | | render_diff | Render a unified diff with + / - highlighting. | | devices_status | Return the user's currently linked Agentics devices. |

Box types

text, markdown, list, checklist, table, data, agent, image, html, diff, devices, chart, file, research, agent-browser, agent-code, agent-files.

Presets

Welcome, Cockpit, Concierge, Powerboard, Operator, Workbench, Workshop, Chat, Comparison, Stage.

Run agentics --list-presets for the live list.

Powerboard allocation rules

The powerboard is a dynamic grid that re-arranges itself every time a box is added, removed, hidden, or restored.

1. Up to maxVisible (default 8) boxes are rendered at once.
2. When a new box pushes the count above the cap, the oldest non-pinned box is hidden.
3. Pinned boxes (pinned: true) cannot be hidden, evicted, or shrunk for room. The Primary Agent terminal and active sub-agents are pinned by default.
4. Within the visible set, layout slots are assigned in this order: pinned first, then by descending priority, then by creation order.
5. The orb cell is auto-fitted into the largest empty rectangle when no layout pins it explicitly.

Sub-agent lifecycle

deploy_agent creates a pinned agent box on the board, calls the backend /v1/agent/task endpoint, and maps every identifier the API returns (taskId, jobId, id, task_id) to that box. The box stays pinned while the job is running. As the server emits job.started, job.progress, job.chunk, job.complete, or job.error events, the box content is rewritten in place to show the live state. On completion or failure the box is unpinned so it can age out naturally, and its identifier mappings are released. On API failure the box is updated with the error and removed automatically after six seconds.

Authentication

The first launch prompts for login or sign-up if no token is found. Successful auth is cached at ~/.agentics/auth.json with mode 0600. A rejected saved token clears the cache and re-prompts.

Companion registration

Every session registers the CLI with the backend companion endpoint using a randomly generated cli_<hex> device id. The hostname and platform are reported so the user's other Agentics surfaces can see this terminal as a live device.

License

Proprietary. See LICENSE. Copyright AgenticsAI (Pty) Ltd. Contact [email protected].

Links

• Homepage: https://agentics.co.za
• Console: https://agentics.co.za/dashboard
• Contact: [email protected]