npm package: @izqut/izcode
Description: AI coding assistant CLI with OpenAI-compatible tool calling
Author: Your Name
Latest version: 0.1.8

# izcode

`izcode` is a TypeScript CLI coding agent for OpenAI-compatible models. It supports tool calling, local project sessions, `@path` mentions, smart file discovery, targeted region editing, safety modes, undo, and Plan Mode.

## Install

```bash
npm install
npm run build
npm link
```

After linking:

```bash
izcode
```

On startup, `izcode` now renders a styled `IZCODE` terminal banner and status panel (mode/model/permission/trace/session).

Long-session context management:

- `izcode` now auto-compacts long conversation history into a checkpoint summary when context grows too large.
- It keeps recent user turns in full and compresses older turns, reducing context overflow risk during long task execution.
- Compaction events are visible in trace logs.

## Configuration

On first run, `izcode` creates:

- A local web setup page opens automatically in your browser so you can fill settings there.
- If browser setup is unavailable, it falls back to terminal prompts.
- `~/.izcode/settings.json`
  - `apiKey`
  - `baseURL`
  - `model`
  - `permissionMode` (`safe` or `autonomous`)

Per project, `izcode` creates:

- `./.izcode/sessions/*.json` (chat sessions)
- `./.izcode/current_session.json` (current session pointer)
- `./.izcode/undo/` (write backups for `/undo`)

## Commands

- `/help` show command list
- `/mode` switch between `agent` and `plan` mode explicitly
- `/plan` enter or exit plan mode
- `/init` scan project and create/update `IZCODE.md`
- `/trace` toggle or set trace (`on|off|minimal|normal|verbose`)
- `/resume` load previous session
- `/clear` clear current session context
- `/permission` choose `safe` or `autonomous`
- `/undo` revert last file write
- `/new` start a new session
- `/exit` save and quit

Input UX:

- Slash commands have real-time suggestions while typing.
- Type `/` to list commands; type `/p` to narrow to `/permission`.
- `@` references also have real-time suggestions; type `@i` to list matching files/folders.
- Input prompt shows inline mode/help hints for smoother flow.
- Use `Up/Down` to select, `Tab` to complete, and `Enter` to submit.
- In `@` suggestions, `Enter` also completes the selected path (does not auto-send).
- Press `Esc` to hide current `@` suggestion list.
- Use `Shift+Tab` to quickly toggle Plan Mode.
- Live trace is on by default (`normal`) so you can see model/tool/file-operation progress in real time.
- While waiting for model response, loading animation is shown. If the model is reasoning-capable, it shows `🧠 thinking...`.
- For explicit "run/execute" requests, the agent now prefers real tool execution (especially shell) over manual-only instructions.
- If a first model pass returns no tool calls on an execution request, `izcode` automatically retries once with required tool-calling.
- For long-running commands (for example local dev/http servers), `izcode` starts them in background and returns terminal control quickly.

## Plan Mode

Plan Mode is planning-first workflow:

- Enter via `/plan` or `Shift+Tab`.
- The agent can ask interactive questions using:
  - single choice
  - multi choice
  - free-text input
- In plan mode, mutating actions are blocked (`writeFile`, `replace_in_file`, `replace_in_region`, `run_shell_command`).
- The agent returns a complete plan.
- Then you confirm:
  - `Yes` => exit plan mode and execute approved plan
  - `No` => exit plan mode and wait for your next command
- While waiting on model responses, press `Esc` to stop the current in-flight task.

## Context References

Use `@path` in prompt text, for example:

- `@src/index.ts`
- `@src/`

`@` entries are treated as **path mentions only** (Codex-style): they do not inject full file content into prompt.

If an `@` token is incomplete (for example `@src/uti`), `izcode` opens an interactive file/folder picker to complete it.

For precise large-file changes, the agent is expected to use:

- `find_in_file` to locate target line ranges
- `read_file_region` to read only needed sections
- `replace_in_region` for minimal scoped edits

## IZCODE.md Rules

`izcode` supports project rule files via `IZCODE.md`:

- Run `/init` to generate or update a project-level `IZCODE.md`.
- `/init` now generates AGENTS-style repository guidance sections:
  - `Project Structure & Module Organization`
  - `Build, Test, and Development Commands`
  - `Coding Style & Naming Conventions`
  - `Testing Guidelines`
  - `Commit & Pull Request Guidelines`
- `/init` uses current LLM config to analyze project snapshot and produce concise, actionable bullets, with automatic local fallback heuristics when LLM analysis fails.
- Snapshot metadata (project type, primary languages, detected stack, scan count) is embedded for traceability.
- During `/init`, a live loading indicator is shown while scanning/analyzing.
- Existing file is merged/updated (auto-generated repository-guidelines block is refreshed, user rules are preserved).
- At runtime, rules are loaded automatically:
  - project root `IZCODE.md` is applied
  - nested `IZCODE.md` files (for mentioned paths) override root rules
- Loaded rule sources are shown in trace output and injected into system prompt.


## Smart File Discovery

The agent can discover likely files by intent using `find_relevant_files`.

Examples:

```bash
agent> fix the login bug
agent> add logging to database queries
agent> update the API endpoint for users
```