Openchatci

OpenChatCi

> [!IMPORTANT] > This project has been renamed to ChatWalaʻau and moved to a new repository. > This repository is no longer maintained and is kept only as a historical pointer, frozen at the final openchatci release (v0.49.0). > > ➡️ New home: https://github.com/motojinc25/chatwalaau

| | Old (this repository) | New | |---|---|---| | Project name | OpenChatCi | ChatWalaʻau | | GitHub | motojinc25/openchatci | motojinc25/chatwalaau | | PyPI | openchatci (frozen at v0.49.0) | chatwalaau | | Install | pip install openchatci (legacy, v0.49.0 only) | pip install chatwalaau | | CLI command | openchatci | chatwalaau |

Why the new name? walaʻau is a Hawaiian word meaning "to chat, talk, converse" — a better fit for what the project does. All ongoing development, new features, and releases now happen in the ChatWalaʻau repository.

> The content below is preserved as-is from the final OpenChatCi release for historical reference.

---

The localhost AI Agent Runtime -- Chat UI, Tools, RAG, and MCP in one pip install

[](https://pypi.org/project/openchatci/) [](LICENSE.md) [](https://pypi.org/project/openchatci/)

OpenChatCi is a full-stack AI agent runtime that runs entirely on localhost. It connects a modern chat UI to AI agents via the AG-UI protocol, with built-in tools, RAG pipeline, MCP integration, and an OpenAI-compatible API -- all from a single pip install.

Why OpenChatCi?

• One command, full stack -- pip install openchatci gives you Chat UI + Agent Runtime + Tools + RAG. No Docker, no cloud setup.
• MCP native -- Claude Desktop-compatible config. Connect any MCP server. MCP Apps render interactive UI in chat.
• Your data stays local -- File-based sessions, ChromaDB vectors, and uploads never leave your machine.
• OpenAI-compatible API -- Expose your agent as /v1/responses for any app using the OpenAI SDK.

> Hawaii-built, powered by Microsoft Agent Framework

---

UI Preview

Weather Tools | Mermaid Diagrams | Image Analysis

DevUI | Search Session | Image Generation

---

Quick Start

pip install openchatci
openchatci init
# Edit .env and set AZURE_OPENAI_ENDPOINT
az login
openchatci

Open: http://localhost:8000/chat

---

Features

Chat & UI

• Chat with AI agents via AG-UI protocol (SSE streaming)
• Rich message rendering: Markdown, code blocks, math (KaTeX), Mermaid diagrams
• LLM reasoning visualization with collapsible thinking blocks
• Web search with inline citation links
• Voice input via microphone with Whisper transcription
• Text-to-Speech playback and download via ElevenLabs
• Multimodal image analysis (file attachment, drag-and-drop, URL)
• Session management: save, search, pin, archive, fork, rename
• Context window consumption display with warning levels
• Per-turn token usage display
• Three layout scenarios: Chat, Popup, Sidebar
• Multilingual chat with browser auto-translation suppressed

Agent Tools

• Image generation, editing, and Canvas mask editor via Azure OpenAI gpt-image-1.5
• Weather tools with rich card widgets (Open-Meteo, no API key)
• Coding tools (file read/write, shell execution, file search)
• Prompt Templates: save, manage, and insert reusable prompts from "+" menu and message actions
• Agent Skills: portable domain knowledge packages with progressive disclosure

Platform

• MCP Integration: connect external tools via Model Context Protocol (Claude Desktop-compatible config)
• MCP Apps: interactive UI rendered in sandboxed iframes for MCP tools with _meta.ui resources
• RAG Pipeline: PDF ingestion with ChromaDB vector search, Azure OpenAI embedding, and source citations
• Batch Processing: async job queue via Core MCP Server with real-time MCP Apps dashboard
• Multi-model switching: switch between OpenAI models mid-conversation with per-model reasoning and context window
• Session management: save, search, organize into folders, pin, archive, fork, rename
• Background Responses: long-running agent timeout prevention with stream resumption
• Context window consumption display with warning levels
• Per-turn token usage display
• OpenAI-compatible API: expose agent as /v1/responses endpoint for external apps via OpenAI SDK
• Unified API authentication: single API_KEY Bearer token protects /v1/responses, every write REST endpoint, and the AG-UI chat stream for non-loopback (LAN) callers; same-machine clients always bypass
• CLI Client: chat, session/template/model management, TTS, and upload from the command line with local preflight validation for filename, MIME type, and size
• HTTPS/TLS support for LAN access with Secure Context (mkcert recommended)
• Multilingual chat with browser auto-translation suppressed
• Three layout scenarios: Chat, Popup, Sidebar

---

Architecture

The platform connects the UI and agent runtime through the AG-UI protocol.

---

Development Setup

Prerequisites

| Tool | Version | Install | | --------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | Node.js | 22+ | https://nodejs.org/ | | pnpm | 10+ | npm install -g pnpm | | Python | 3.12+ | https://www.python.org/ | | uv | 0.9+ | https://docs.astral.sh/uv/ | | Azure CLI | 2.x | https://learn.microsoft.com/cli/azure/install-azure-cli |

---

1. Azure Authentication

The backend authenticates to Azure OpenAI via AzureCliCredential. You must log in before starting.

az login

Select the subscription if needed:

az account set --subscription 

---

2. Backend Setup

Windows (PowerShell):

cd backend
copy .env.sample .env
# Edit .env and set your Azure OpenAI endpoint
notepad .env
uv sync --prerelease=allow

macOS / Linux:

cd backend
cp .env.sample .env
# Edit .env and set your Azure OpenAI endpoint
nano .env
uv sync --prerelease=allow

.env configuration (required):

AZURE_OPENAI_ENDPOINT=https://.openai.azure.com/
AZURE_OPENAI_MODELS=gpt-4o

---

3. Frontend Setup

cd frontend
pnpm install

---

4. Start Development Servers

Open two terminals:

Terminal 1 -- Backend:

cd backend
uv run uvicorn app.main:app --reload --app-dir src

Backend starts at http://localhost:8000

Terminal 2 -- Frontend:

cd frontend
pnpm dev

Frontend dev server starts at http://localhost:5173 (API requests are proxied to the backend)

---

5. Production Build

cd frontend
pnpm build

cd ../backend
uv run uvicorn app.main:app --app-dir src

The backend serves both frontend build artifacts and the API at http://localhost:8000

---

CLI Usage

Server Commands

openchatci                                Start the server
openchatci init                           Generate .env from template
openchatci init --force                   Overwrite existing .env
openchatci --host 0.0.0.0                 Bind to all interfaces
openchatci --port 9000                    Use custom port
openchatci --skip-auth-check              Skip Azure CLI login check
openchatci --ssl-certfile cert.pem \
           --ssl-keyfile key.pem          Enable HTTPS (LAN access)
openchatci --version                      Show version

Client Commands

Interact with a running OpenChatCi instance from the command line. All client commands support --json for machine-readable output and --base-url / --api-key for remote server access.

# Chat with the agent (single-shot)
openchatci chat "What is the weather in Tokyo?"

# Interactive chat (REPL mode)
openchatci chat -i

# Chat with specific model and session
openchatci chat "hello" -m gpt-4o -s 

# Session management
openchatci sessions list
openchatci sessions get  --messages
openchatci sessions delete 
openchatci sessions export  -o backup.json

# Template management
openchatci templates list
openchatci templates create -n "Bug Report" -c "Describe the bug..."

# Model info
openchatci models list

# Text-to-Speech
openchatci tts "Hello world" -o greeting.mp3

# File upload
openchatci upload document.pdf -s 

# JSON output for scripting / agent-to-agent
openchatci sessions list --json | jq '.[].thread_id'

# Remote server with HTTPS (self-signed cert)
openchatci sessions list --base-url https://192.168.1.10:8000 --no-verify

openchatci upload validates the local file before sending the request: the file must exist, the sanitized filename must remain valid, the MIME type must be one of the supported image formats or PDF, and the size limit must stay within 20MB for images or 50MB for PDFs.

Environment variables for client configuration:

OPENCHATCI_URL=http://localhost:8000       # Default server URL
OPENCHATCI_API_KEY=sk-your-key             # Bearer token (reuses API_KEY if not set)

---

Tech Stack

| Layer | Technology | Purpose | | -------- | ---------------------------- | ------------------------------ | | Frontend | React 19 + TypeScript + Vite | UI framework | | Frontend | Tailwind CSS + shadcn/ui | Styling + Components | | Frontend | Biome | Format + Lint | | Backend | FastAPI + Python 3.12+ | API server | | Backend | Microsoft Agent Framework | Agent execution + Tool control | | Backend | Ruff | Format + Lint | | Package | uv | Python dependency management | | Package | pnpm | Node.js dependency management |

---

Optional Features

Prompt Templates

Save and reuse prompt templates from the chat interface:

TEMPLATES_DIR=.templates

• Click + button > Use template to open the management modal
• Create, edit, delete templates with name, category, and body
• Insert to Chat pastes the template into the input (editable before send)
• Click the FileText icon on any user message to save it as a template

Templates are stored as individual JSON files in the configured directory.

---

Image Generation

Generate and edit images via Azure OpenAI gpt-image-1.5:

IMAGE_DEPLOYMENT_NAME=gpt-image-1.5

• generate_image: create images from text prompts with configurable size, quality, format, background, and count (1-4)
• edit_image: modify existing session images using text prompts (prompt-based)
• Canvas Mask Editor: click the Edit button on any generated image to open a full-screen mask editor
• Draw over areas to edit with brush tools (S/M/L), eraser, undo/redo
• Enter a prompt and click Generate -- the agent edits only the masked region
• Generated images displayed inline in chat with click-to-open full-size
• Images stored in session upload directory and persist across reloads

The agent automatically uses these tools when users request image creation or editing. No opt-in flag needed -- the feature activates when IMAGE_DEPLOYMENT_NAME is set.

---

Coding Tools

Enable AI-powered file operations and shell execution:

CODING_ENABLED=true
CODING_WORKSPACE_DIR=C:\path\to\workspace
# Optional: bound file_read output to protect memory + context window
# CODING_FILE_READ_MAX_BYTES=1048576   # 1 MiB default

file_read now stats the target before reading and caps the output at CODING_FILE_READ_MAX_BYTES (default 1 MiB). When the cap or the line limit is hit, the response ends with an explicit [TRUNCATED BY BYTES: ...] / [TRUNCATED BY LIMIT: ...] marker that tells the agent how to paginate with offset=N.

---

Text-to-Speech

Enable on-demand TTS for messages via ElevenLabs:

ELEVENLABS_API_KEY=your-api-key
TTS_MODEL_ID=eleven_multilingual_v2
TTS_VOICE_ID=your-voice-id

Speaker button plays audio, download button saves MP3 file. Audio is cached to avoid duplicate API calls.

---

Agent Skills

Extend the agent with domain knowledge packages (Agent Skills specification):

SKILLS_DIR=.skills

Place SKILL.md files in subdirectories. The agent discovers and loads skills on demand:

.skills/
  my-skill/
  +-- SKILL.md          # Required: instructions + metadata
  +-- scripts/          # Optional: executable code
  +-- references/       # Optional: documentation
  +-- assets/           # Optional: templates, resources

Skills use progressive disclosure to minimize context window consumption (~100 tokens per skill when idle).

---

MCP Integration

Connect external tools and services via Model Context Protocol using the Claude Desktop-compatible configuration format:

MCP_CONFIG_FILE=mcp_servers.json

Create a mcp_servers.json file (see backend/mcp_servers.sample.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

• stdio servers (with command): OpenChatCi spawns the process and communicates via stdin/stdout
• HTTP/SSE servers (with url): OpenChatCi connects to a running remote server
• MCP tools appear alongside built-in tools (Weather, Coding, Image Generation)
• Tool calls display with categorized icons: built-in tools have dedicated icons, Skills tools show BookOpen/FileText, MCP tools show Plug
• Server lifecycle managed automatically (startup/shutdown with zombie process prevention)
• Optional per-server fields (Claude Desktop-compatible, ignored elsewhere):
• "load_prompts": true -- set when your MCP server implements prompts/list (most community servers are tools-only; the default is false so filesystem, git, github, etc. connect cleanly out of the box)
• "load_tools": false -- skip the tools/list probe for a tools-only server's prompts-only mode
• "request_timeout": 30 -- per-call timeout in seconds forwarded to MAF
• Reuse your existing Claude Desktop / Claude Code / Cursor MCP configurations

---

MCP Apps

MCP tools that declare a _meta.ui resource automatically render interactive UI within chat messages. The HTML View runs in a secure double-iframe sandbox with CSP enforcement.

# Optional: change the sandbox proxy port (default 8081)
# MCP_APPS_SANDBOX_PORT=8081

• Automatic discovery: UI-enabled MCP tools detected at server startup
• Double-iframe sandbox: Views run on a separate origin with no access to host DOM, cookies, or storage
• CSP enforcement: external resources blocked by default; servers declare required domains via metadata
• View-to-Server proxying: all View interactions proxied through the Host (auditable)
• Display modes: inline (in chat) and fullscreen
• Session persistence: View HTML stored as files for reload restoration
• **Progressiv

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: motojinc25
• Source: motojinc25/openchatci
• License: Apache-2.0
• Homepage: https://pypi.org/project/openchatci/

Install and usage instructions live in the source repository linked above.