For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Overview

@push.rocks/smartchat gives you everything you need to build conversational AI interfaces — in the terminal and on the web. It ships three entry points:

Entry Point	Import Path	What You Get
Core	`@push.rocks/smartchat`	`ChatSession` — headless conversation state management
CLI	`@push.rocks/smartchat/cli`	`startChat()` — full-featured terminal TUI (ink-based)
Web	`@push.rocks/smartchat/web`	`<smartchat-window>` and friends — Lit-based web components

Under the hood, every turn calls @push.rocks/smartagent's runAgent(), giving you streaming tokens, tool calling, and multi-step agentic loops out of the box.

Usage

🧠 Core — `ChatSession`

ChatSession manages in-memory conversation history and wraps the agent loop. It's headless — bring your own UI or use it from scripts, bots, and backend services.

import { ChatSession } from '@push.rocks/smartchat';
import type { IChatSessionOptions, IChatCallbacks, IChatUsage } from '@push.rocks/smartchat';

// Create a session with your model and optional tools
const session = new ChatSession(
  {
    model: myLanguageModel,       // LanguageModelV3 from @push.rocks/smartai
    system: 'You are a helpful coding assistant.',
    tools: myToolSet,             // optional ToolSet
    maxSteps: 20,                 // max agentic steps per turn (default: 20)
  },
  {
    onToken: (delta) => process.stdout.write(delta),
    onToolCall: (name, input) => console.log(`🔧 ${name}`),
    onToolResult: (name, result) => console.log(`✅ ${name}`),
    onTurnComplete: (result) => console.log(`Done — ${result.usage.totalTokens} tokens`),
    onError: (err) => console.error(err),
  }
);

// Send a message and get the result
const result = await session.send('Explain the builder pattern in TypeScript');
console.log(result.text);

// Inspect state
console.log(session.getUsage());    // { inputTokens, outputTokens, totalTokens, turns }
console.log(session.getMessages()); // full conversation history
console.log(session.isBusy());      // false (turn complete)

// Manage conversation
session.clear();                    // reset history + usage
session.setMessages(savedHistory);  // restore a saved session
session.updateOptions({ system: 'New system prompt' });
session.updateCallbacks({ onToken: null });

`IChatSessionOptions`

Property	Type	Description
`model`	`LanguageModelV3`	The language model to use (required)
`system`	`string`	System prompt for the agent
`tools`	`ToolSet`	Tools available to the agent
`maxSteps`	`number`	Max agentic steps per turn (default: `20`)

`IChatCallbacks`

Callback	Signature	When It Fires
`onToken`	`(delta: string) => void`	Each streamed text token
`onToolCall`	`(name: string, input: unknown) => void`	Tool call starts
`onToolResult`	`(name: string, result: string) => void`	Tool call completes
`onTurnComplete`	`(result: IAgentRunResult) => void`	Turn finishes
`onError`	`(error: Error) => void`	Error occurs

`IChatUsage`

Field	Type
`inputTokens`	`number`
`outputTokens`	`number`
`totalTokens`	`number`
`turns`	`number`

💻 CLI — Terminal TUI

Launch a beautiful, interactive chat right in your terminal. Built with ink (React for CLIs).

import { startChat } from '@push.rocks/smartchat/cli';
import type { IStartChatOptions } from '@push.rocks/smartchat/cli';

await startChat({
  model: myLanguageModel,
  system: 'You are a friendly assistant.',
  tools: myToolSet,
  maxSteps: 30,
  modelName: 'Claude Opus',   // displayed in the header & status bar
});

Features

⚡ Real-time streaming — tokens appear as they're generated
🔧 Tool call visibility — see tool invocations inline
📊 Status bar — model name, token usage, turn count
⌨️ Keyboard shortcuts:
- Ctrl+C — exit
- Ctrl+L — clear conversation
💬 Slash commands:
- /clear — reset the conversation
- /quit or /exit — exit the TUI

`IStartChatOptions`

Property	Type	Description
`model`	`LanguageModelV3`	The language model (required)
`system`	`string`	System prompt
`tools`	`ToolSet`	Tools for the agent
`maxSteps`	`number`	Max agentic steps per turn
`modelName`	`string`	Display name shown in header & status bar

🌐 Web — Lit Web Components

Drop a full chat UI into any web app. Three custom elements, fully themeable with CSS custom properties.

import '@push.rocks/smartchat/web';
import { ChatSession } from '@push.rocks/smartchat';

// Create a session
const session = new ChatSession({
  model: myLanguageModel,
  system: 'You are a helpful assistant.',
});

// Get the element and wire it up
const chatWindow = document.querySelector('smartchat-window');
chatWindow.chatSession = session;

<smartchat-window placeholder="Ask me anything..."></smartchat-window>

Components

Element	Description
`<smartchat-window>`	Full chat window — message list + input area. Pass a `ChatSession` via the `chatSession` property.
`<smartchat-message>`	Single message bubble. Attributes: `role` (`user` / `assistant` / `tool`), `content`, `toolName`.
`<smartchat-input>`	Input field + send button. Fires `send` custom event. Attributes: `disabled`, `placeholder`.

🎨 Theming with CSS Custom Properties

Every visual aspect is customizable:

smartchat-window {
  /* Layout */
  --smartchat-bg: #111827;
  --smartchat-text: #e5e7eb;
  --smartchat-font: system-ui, -apple-system, sans-serif;
  --smartchat-radius: 12px;
  --smartchat-border: #1f2937;
  --smartchat-muted: #6b7280;

  /* User messages */
  --smartchat-user-bubble: #2563eb;
  --smartchat-user-text: #fff;

  /* Assistant messages */
  --smartchat-assistant-bubble: #374151;
  --smartchat-assistant-text: #e5e7eb;

  /* Tool messages */
  --smartchat-tool-bubble: #1e293b;
  --smartchat-tool-text: #94a3b8;
  --smartchat-tool-accent: #6366f1;

  /* Input area */
  --smartchat-input-bg: #1f2937;
  --smartchat-input-border: #374151;
  --smartchat-input-focus: #6366f1;
  --smartchat-input-text: #e5e7eb;
  --smartchat-input-placeholder: #6b7280;

  /* Send button */
  --smartchat-send-bg: #6366f1;
  --smartchat-send-text: #fff;

  /* Streaming cursor */
  --smartchat-cursor: #6366f1;
}

Architecture

@push.rocks/smartchat
├── ts/              → Core module (ChatSession, interfaces)
├── ts_cli/          → CLI TUI (ink + React)
└── ts_web/          → Web components (Lit)

Core (ts/) is headless and dependency-light. CLI and Web layers both import from Core.
CLI (ts_cli/) uses ink with React.createElement (no JSX).
Web (ts_web/) uses Lit with static properties (no decorators).
The agentic loop is powered by @push.rocks/smartagent, which orchestrates multi-step tool calling with any LanguageModelV3 from @push.rocks/smartai.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@push.rocks/smartchat

Install

Issue Reporting and Security