# loccle

> Interactive AI CLI tool for software engineering tasks.

Latest version **1.0.33** (published 2026-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install loccle
pnpm add loccle
yarn add loccle
bun add loccle
```

Provides the command `loccle`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.33 |
| Published | 2026-09-15 |
| First published | 2026-05-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | digitalmedika |
| Maintainers | digitalmedika |
| Keywords | ai, cli, coding-agent, assistant, rust |

## Links

- npm: https://www.npmjs.com/package/loccle
- Repository: https://github.com/digitalmedika/sidoarjo
- Homepage: https://github.com/digitalmedika/sidoarjo#readme
- Issues: https://github.com/digitalmedika/sidoarjo/issues
- npm.io page: https://npm.io/package/loccle

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.0.33 (latest) — 2026-09-15
- 0.0.0-master-202605180047 (master) — 2026-05-18
- 1.0.32 — 2026-09-08
- 1.0.31 — 2026-09-06
- 1.0.30 — 2026-09-03
- 1.0.29 — 2026-07-09
- 1.0.28 — 2026-07-04
- 1.0.27 — 2026-07-03
- 1.0.26 — 2026-07-01
- 1.0.25 — 2026-06-30
- 1.0.24 — 2026-06-30
- 1.0.23 — 2026-06-29
- 1.0.22 — 2026-06-29
- 1.0.21 — 2026-06-27
- 1.0.20 — 2026-06-18
- … 23 more at https://npm.io/package/loccle/versions

## README

# 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](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

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

**Example:**
```bash
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:

```bash
# 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

```bash
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:

```bash
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).

---
_Source: https://npm.io/package/loccle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._