# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**j-cli** (`j`) is a fast CLI productivity tool written in Rust. It provides alias management, daily reports, todo management, AI chat with tool-calling, browser automation, a skill/hook system, and an interactive REPL. Binary name is `j`.

- Rust 2024 edition, minimum rustc 1.93.1
- Published to crates.io as `j-cli`
- All UI text is in Chinese (中文)

## Common Commands

```bash
# Build
cargo build                        # Debug build
cargo build --release              # Release build
cargo build --features browser_cdp # Build with Chrome DevTools Protocol support

# Test
cargo test                         # Run all tests
cargo test --all-features          # Run tests including CDP features
cargo test <test_name>             # Run a single test

# Code quality
cargo fmt                          # Format code
cargo clippy -- -D warnings        # Lint (treats warnings as errors)

# Pre-commit (format + lint + test)
make pre-commit

# Install locally
make install                       # Builds release and copies to /usr/local/bin/j

# Version management
make bump-version                  # Increment patch version in Cargo.toml
make set-version V=x.y.z           # Set specific version
make publish                       # Bump version + build + tag + push + publish to crates.io
```

## Architecture

### Entry Flow

`main.rs` → If no args, enters interactive REPL (`interactive::run_interactive`). Otherwise, attempts clap parsing (`cli::Cli`). If clap fails (unrecognized subcommand), falls back to alias-open logic (`command::open::handle_open`).

### Module Structure

```
src/
├── main.rs              # Entry point, arg routing
├── cli.rs               # Clap command/subcommand definitions (SubCmd enum)
├── constants.rs         # Global constants (paths, version, data dirs)
├── assets.rs            # Embedded assets (rust-embed)
├── config/              # YAML config loading/saving (~/.jdata/config.yaml)
├── command/
│   ├── handler.rs       # CommandHandler trait + command_handlers! macro
│   ├── mod.rs           # dispatch() function routing SubCmd → handlers
│   ├── alias.rs         # set/remove/rename/modify aliases
│   ├── category.rs      # note/denote category tagging
│   ├── list.rs          # ls command
│   ├── open.rs          # Alias open logic (apps, URLs, editors, browsers)
│   ├── report.rs        # Daily report system
│   ├── script.rs        # Script creation/execution (j concat)
│   ├── system.rs        # System commands (contain, change, clear, help)
│   ├── time.rs          # Countdown timer
│   ├── update.rs        # Self-update
│   ├── todo/            # Todo TUI (ratatui-based)
│   ├── help/            # Help text
│   └── chat/            # AI chat system (~largest module)
├── interactive/         # REPL mode (rustyline, tab completion, shell mode)
├── tui/                 # Shared TUI editor widget
└── util/                # Logging macros, markdown rendering, fuzzy search, HTML extract
```

### Chat Module (`command/chat/`) — Largest Subsystem

The AI chat is a full TUI application with tool-calling, streaming, and context management:

- **handler/** — TUI event loop (`tui_loop.rs`), chat logic (`chat.rs`), config UI, archive restore, tool confirmation dialog, message browse mode
- **agent.rs** — Agent loop: sends messages to LLM, processes tool calls in a loop until done
- **api.rs** — OpenAI-compatible API client (streaming via `async-openai`)
- **tools/** — 15+ built-in tools (Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Browser, Ask, BackgroundRun, Compact, Task*, LoadSkill, RegisterHook). Each tool is a separate file
- **tools/file/** — File operation tools (read, write, edit, glob, grep)
- **tools/task/** — Task management tools (create, list, get, update)
- **compact.rs** — 3-layer context compaction (micro_compact → auto_compact → Compact tool)
- **permission.rs** — `.jcli` file permission system (allow/deny rules for tool execution)
- **hook.rs** — 3-tier hook system (user → project → session level)
- **skill.rs** — Skill loading from `~/.jdata/agent/skills/`
- **storage.rs** — Chat history persistence, agent config loading
- **ui/** — UI rendering (chat view, config view, archive list)
- **markdown/** — Markdown parsing and syntax highlighting for chat display
- **theme.rs** — Color themes (dark, light, dracula, gruvbox, monokai, nord)
- **render_cache.rs** — Rendered message caching
- **archive.rs** — Conversation archive/restore
- **autocomplete.rs** — `@skill` autocomplete in input

### Key Patterns

- **CommandHandler trait + `command_handlers!` macro**: Declarative command registration in `handler.rs`. Each command is a struct implementing `CommandHandler::execute()`.
- **`dispatch()` function**: Maps `SubCmd` enum variants to handler structs in `command/mod.rs`.
- **Logging macros**: `info!`, `error!`, `usage!`, `debug_log!(config, ...)` defined in `util/log.rs`. `debug_log!` only prints in verbose mode.
- **Agent file logging**: `log_info()` and `log_error()` in `util/log.rs` write to `~/.jdata/agent/logs/`.
- **Config**: `YamlConfig` wraps `~/.jdata/config.yaml`. Agent config is separate JSON at `~/.jdata/agent/data/agent_config.json`.
- **Data directory**: All user data lives under `~/.jdata/` (customizable via `J_DATA_PATH` env var).
- **Optional feature**: `browser_cdp` feature flag enables Chrome DevTools Protocol support via `chromiumoxide` crate. Without it, browser tools use HTTP-based "Lite" mode.
- **Optional feature**: `browser_cdp` — enables Chromium automation via `chromiumoxide`