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

npm install
npm run build
npm link

After linking:

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:

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