# oc-top

**Repository Path**: gabrielslls/oc-top

## Basic Information

- **Project Name**: oc-top
- **Description**: Real-time TUI monitor for OpenCode - like top/iftop for LLM calls.
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# oc-top 🐙

> Real-time TUI monitor for OpenCode - like `top`/`iftop` for LLM calls

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)

**oc-top** (八爪监控) 是一个类似 `top`/`iftop` 的终端工具，用于实时监控 OpenCode 模型调用情况。直接读取本地 SQLite 数据库，零集成、零配置、完全本地运行。

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔄 **Real-time** | 1-second refresh rate |
| 📊 **4 Views** | Model / Provider / Agent / Tool |
| 📡 **Live Stream** | Last 20 calls with status |
| 🌐 **i18n** | English / 中文 |
| 🔌 **MCP Highlighting** | Identify MCP tools (may have quota limits) |
| 🔍 **Filter** | Filter by name/provider |
| ⌨️ **Keyboard-first** | Full keyboard navigation |
| 🔒 **Privacy** | 100% local, no data upload |
| 🚀 **Zero-config** | Works out of the box |

## 📦 Installation

### Prerequisites

- Node.js 18+
- OpenCode installed with data at `~/.local/share/opencode/`

### Quick Start

```bash
# Clone
git clone git@github.com:gabrielslls/oc-top.git
cd oc-top

# Install
npm install

# Build
npm run build

# Run
npm start
```

## 🎮 Usage

```bash
npm start
```

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` | Quit |
| `p` | Pause/Resume |
| `s` | Cycle sort |
| `f` | Filter mode |
| `l` | Switch language |
| `h` | Help screen |
| `Tab` | Next view |
| `Shift+Tab` | Previous view |
| `↑`/`↓` | Selected row cursor |
| `Enter` | Drill down to live calls |
| `Esc` | Back from Detail view |

## ⚙️ Options

| Flag | Description |
|------|-------------|
| `--db <path>` | Specify custom OpenCode SQLite database path |
| `--help` | Show help information |
| `--version` | Show current version |

## 📊 Views

### 1. Model View
Statistics by model with live call stream

### 2. Provider View
Aggregate statistics by provider (baidu, cucloud, astroncodingplan)

### 3. Agent View
Statistics by agent (Sisyphus, Atlas, oracle, etc.)

### 4. Tool View
Tool call statistics with MCP highlighting (magenta + ⚡)

## 🔌 MCP Tools

The following tools are highlighted (may have quota limits):
- `websearch_web_search_exa` - Exa Search API
- `context7_query-docs` - Context7 Documentation
- `context7_resolve-library-id` - Context7 Library Resolution
- `grep_app_searchGitHub` - GitHub Code Search
- `skill_mcp` - Dynamic MCP calls

## 📁 Project Structure

```
oc-top/
├── src/
│   ├── index.ts          # Entry point
│   ├── app.tsx           # Main TUI component
│   ├── db/connection.ts  # SQLite queries
│   ├── i18n/index.ts     # Internationalization
│   └── types/index.ts    # TypeScript types
├── locales/
│   ├── en.json           # English
│   └── zh-CN.json        # Chinese
├── _legacy/
│   └── python-monitor/   # Legacy Python tool
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── LICENSE
└── README.md
```

## 🔧 Development

```bash
npm install
npm run build
npm start
```

## 📄 License

[MIT](LICENSE)

---

Made with ❤️ by Gabriel88