Terminal setup and usage

The terminal provider works with no credentials and no required config.

How it works

terminal.config() spawns the standalone tuichat binary as a subprocess and drives it over JSON-RPC. The binary auto-downloads from GitHub Releases the first time you run it. In a TTY it boots the rich UI. In a non-TTY context, such as CI or piped input, it falls back to a synchronous readline loop, so the same agent code works for scripted integration tests.

import { Spectrum } from "spectrum-ts";
import { terminal } from "spectrum-ts/providers/terminal";

const app = await Spectrum({
  providers: [terminal.config()],
});

for await (const [space, message] of app.messages) {
  if (message.content.type === "text") {
    await space.send(`echo: ${message.content.text}`);
  }
}

No credentials, no config. Import and run.

Config

terminal.config({
  commands: [
    { name: "/clear", description: "Clear conversation memory" },
    { name: "/whoami", description: "Print sender details" },
  ],
});

Option	Type	Default	Description
`commands`	`{ name: string; description?: string }[]`	`[]`	Slash commands surfaced in the TUI’s command picker. Names must match `/^\/[A-Za-z0-9_-]+$/`.

Slash commands arrive as regular text messages with the command string as the content. Handle them in your for await loop the same way you’d handle any text.

Working with multiple spaces

By default the TUI starts on chat-1. New chats opened with Ctrl+N get chat-2, chat-3, and so on. To open a named space programmatically, pass an id:

import { terminal } from "spectrum-ts/providers/terminal";

const t = terminal(app);
const debug = await t.space.get("debug");
await debug.send("agent online");

Calling space.get() ensures the chat exists in the sidebar. This is useful for kicking off a conversation before any user input.

When to use it

Iterating on agent logic: every Spectrum API works exactly as it would in production, so behavior you build here ships unchanged.
Integration tests: pipe stdin in non-TTY mode and assert on stdout. CI does not need a TUI.
CLI tools: use the same handler shape as any multi-platform deployment, with reactions and replies as first-class events.

Get started

Core concepts

Content

Providers

Advanced

Integrations

Best Practices

Troubleshooting

Terminal setup and usage

How it works

Config

Working with multiple spaces

When to use it

​How it works

​Config

​Working with multiple spaces

​When to use it

How it works

Config

Working with multiple spaces

When to use it