loccle

Loccle

Loccle is an AI coding assistant Command Line Interface (CLI) built with Rust. It connects to OpenAI-compatible LLM endpoints (chat completions) to execute software engineering tasks autonomously using a suite of built-in tools.

Architecture

The CLI uses a shared Rust library as the first step toward a Tauri desktop adapter. See ARCHITECTURE.md for reusable APIs, UI boundaries, and remaining agent/tool isolation work.

CLI Arguments

The application accepts command-line arguments to configure connection settings and the working directory.

Short Flag	Long Flag	Type	Required?	Description
-m	--model	String	Yes	Name of the LLM model to use (e.g., gpt-4o, antigravity/gemini-3.7-flash-high, claude-3-5-sonnet). No default value.
-k	--key, --api-key	String	Yes	API Key (Bearer authentication token) to access the LLM endpoint. No default value.
-u	--url	String	Yes	LLM API root/base URL endpoint (e.g., http://localhost:20128 or https://api.openai.com/v1). No default value.
-d	--dir, --directory	String	No	Working directory where the AI operates. Defaults to the current directory (.) if not specified.
-	--context-window	Positive integer	No	Context window budget in tokens for the session (default: 1000000). Also supports --context-window=128000.
-v	--version	-	No	Display the installed version, latest npm version, and update instructions when a newer release is available.
-h	--help	-	No	Display help message and CLI usage guide.

Note: The -m, -k, and -u parameters are mandatory, except when using -v / --version or -h / --help. If any of these parameters are omitted, the application will display an error message along with the usage guide.

Check versions with loccle -v (or cargo run -- -v). The npm check has a 5-second timeout; if the registry cannot be reached, the installed version is still displayed and the command exits successfully.

---

How to Run

1. Using Cargo Run

cargo run -- -m <MODEL_NAME> -k <API_KEY> -u <ROOT_URL> [-d <DIRECTORY>]

Example:

cargo run -- \
  -m antigravity/gemini-3.7-flash-high \
  -k sk-aab1bd82368c60e4-36b9f4-73b8c50a \
  -u http://localhost:20128 \
  -d /Users/billymontolalu/Documents/project/loccle

2. Alternative Argument Formats

You can also use equals signs (=) or long flags:

# Using equals sign (=)
cargo run -- -m="gpt-4o" -k="sk-xxx" -u="http://localhost:20128" -d="/path/to/project"

# Using long flags
cargo run -- --model "gpt-4o" --api-key "sk-xxx" --url "http://localhost:20128" --dir "/path/to/project"

3. Building Release Binary

cargo build --release
./target/release/loccle -m <MODEL_NAME> -k <API_KEY> -u <ROOT_URL>

---

Saved Sessions

Conversations are automatically saved to <working-directory>/.loccle/sessions/<session_id>.json, independently of context compaction. Empty sessions are not saved. Each launch starts a new session; previous sessions remain on disk.

• /sessions lists all saved sessions in the current project, newest first, with the active session marked.
• /sessions <session_id> saves the current conversation and resumes the selected session, including its model and conversation context. Enter a prompt to continue.
• /sessions delete <session_id> permanently deletes a saved session snapshot. The active session cannot be deleted; resume another session first. Markdown compaction archives are retained.
• Start Loccle in the same working directory (or use -d) to access the project's saved sessions after restarting.

Snapshots are written atomically before API requests, after completed tool batches, and when returning to the input prompt. An interrupted stream or an unfinished tool batch may not be included in the last snapshot; tools are not automatically replayed on resume. Save failures produce a warning. The API key and endpoint are not stored as session settings; resume uses the current connection and context-window configuration.

Session files contain conversation text and tool output, which may include sensitive data. Keep .loccle/ out of version control. Old Markdown compaction archives in .loccle/conversation_history/ remain readable but cannot be resumed as structured sessions.

Interactive Commands

Inside the interactive CLI session, the following commands are available:

Command	Description	Example
/help, help	Display all available commands and their descriptions.	/help
/model [model_name]	Display the active LLM model or switch to a new model.	/model, /model gpt-4o, /model antigravity/gemini-3.7-flash-high
/compact, compact	Manually condense older conversation context into a summary.	/compact
/context, context	Display current context token usage.	/context
/exit, /quit, exit, quit	Exit the interactive session.	/exit

Press Ctrl+C while waiting for or streaming a model response to cancel the request and return to the prompt without exiting. The incomplete response (including partial tool calls) is discarded; existing conversation history is retained. This shortcut does not cancel tools already running or context compaction. At the prompt, Ctrl+C clears the current input; use /exit or Ctrl+D on an empty prompt to quit.

---

Context Harness

Configure --context-window according to your model's context capacity, for example:

cargo run -- -m gpt-4o -k sk-xxx -u http://localhost:20128 --context-window 128000

• The budget applies throughout the session and does not automatically adjust when /model is used. Start a new session with an appropriate budget if the model's capacity changes.
• Auto-compaction is checked before every agent request, including after tool execution. The threshold is 75% of the budget, taking estimated tool schema size into account.
• 10% of the context window is reserved for output generation. If input still reaches 90% after compaction, the agent step is halted with an error message instead of sending an oversized request.
• /compact triggers manual compaction. A minimum of the 6 most recent messages are preserved; tool call groups and their corresponding results are never split.
• History is saved cumulatively in .loccle/conversation_history/<session>.md. A summarizer failure will not alter either the message buffer or the archive.
• Token counts are based on character heuristic estimation, not the model's exact tokenizer; the budget is not a guarantee against provider token limits.

---

Features & Tools

Loccle comes equipped with a suite of tools autonomously executed by the AI as needed:

• ls: List files and folders within a directory.
• read: Read text file contents with limit and offset support.
• write: Create a new file or overwrite an existing file.
• edit: Replace specific text blocks within an existing file.
• grep: Search for text/regex patterns across files or directories.
• glob: Find files matching wildcard (glob) patterns.
• execute_shell: Run shell/terminal commands.
• write_todos: Create and track a structured task list for multi-step workflows (todos).
• fetch_url: Fetch web page content from a URL and convert it to Markdown (url).
• ask_question: Prompt the user with questions or clarifications and receive their input (question).
• delete: Permanently delete a file or directory (file_path).
• vision: Analyze local PNG, JPEG, GIF, or WebP images using vision models (path, prompt; up to 20 MB).