Local Coding Assistant

Local-first coding assistant that runs on your machine and talks only to Ollama-served models. The goal is to deliver a CLI experience with editing, review, search, and git-aware tools—similar to ChatGPT Codex, Gemini CLI, and Claude Code — without any cloud dependency. Embabel provides the agent runtime, Spring Boot hosts it, and a custom JLine-based REPL exposes the commands.

It requires at least 20 GB of free RAM to run comfortably.

What this project is today

• Interactive shell as the user interface with slash commands for chat, planning, code review, editing, git operations, and more. REST commands are also available.
• Optional Swing desktop GUI (lcaGui) as an alternative to the shell — see Desktop GUI (lcaGui) below.
• Embabel agents for code crafting, review, planning and git operations with safety guardrails.
• Spring Boot entry point with Embabel agents enabled (src/main/java/se/alipsa/lca/LocalCodingAssistantApplication.java).
• Ollama-first configuration using qwen3.8-192k:latest, built from qwen3.8:27b (see src/main/bin/lca).
• Helper script for launching the shell (lca) and installing the models locally.
• Documentation stub for Ollama setup (docs/llm-docs.md).

Launcher script (lca)

If you want to run the latest release, download the launcher script from GitHub Releases. The script stores the executable jar in ~/.local/lib, starts it, and installs Ollama plus the default models when required.

Install the launcher (works with any POSIX shell: bash, zsh, sh, dash, etc.) to any directory in your PATH (e.g., ~/.local/bin, /usr/local/bin, or ~/bin):

# Example using ~/.local/bin (ensure it's in your PATH)
curl -fsSL -o ~/.local/bin/lca \
  https://github.com/Alipsa/local-coding-assistant/releases/latest/download/lca
chmod +x ~/.local/bin/lca

Run the assistant:

lca

Upgrade to the latest version:

lca upgrade

If the launcher script itself changes, download it again from the latest GitHub release.

See Quickstart for more details.

Tutorial

Use the step-by-step walkthrough in docs/tutorial.md, including batch mode examples in docs/examples/.

Configuration

• Change model names, contexts and recipes in src/main/bin/lca, the canonical model configuration shared with models.sh. Re-run lca update or ./models.sh to build the configured models.
• Set spring.ai.ollama.base-url in src/main/resources/application.properties for your Ollama host. The launcher exports LCA_CHAT_MODEL, LCA_FALLBACK_MODEL, LCA_REVIEW_MODEL and LCA_EMBEDDING_MODEL; source runs can set these environment variables explicitly (properties contain the default fallbacks).
• Tune agent behavior via:
  • assistant.llm.model, assistant.llm.temperature.craft, assistant.llm.temperature.review
  • assistant.llm.max-tokens, assistant.system-prompt
  • snippetWordCount, reviewWordCount
  • assistant.context.autocompact-enabled (default true), assistant.context.autocompact-threshold-percent (default 80), assistant.context.autocompact-keep-recent (default 6), assistant.context.compaction-model (optional override; falls back to the session's craft model), assistant.context.compaction-max-tokens (default 1024; independent of assistant.llm.max-tokens so a small chat cap doesn't truncate summaries)

Safety

• Add a .aiexclude file at the project root to block the assistant from reading or modifying sensitive files. Patterns are glob-like and applied relative to the repo (for example: .env, *.pem, credentials.*, build/).
• Add an AGENTS.md file at the project root to define project-specific agent guidance (see docs/agents.md for format and usage).
• Configure command execution policy with assistant.command.allowlist and assistant.command.denylist in src/main/resources/application.properties (comma-separated prefixes like mvn*,git*).
• Local-only mode (assistant.local-only=true) disables remote REST access and web search unless you opt in.
• REST access is local-only by default; configure assistant.rest.remote.enabled, assistant.rest.api-key, assistant.rest.require-https, and assistant.rest.rate-limit.per-minute in src/main/resources/application.properties if needed. Optional OIDC settings live under assistant.rest.oidc.*, and scope enforcement uses assistant.rest.scope.read / assistant.rest.scope.write.
• Optional static analysis for reviews uses assistant.sast.command (for example: semgrep --config auto --json {paths}).
• No telemetry is collected or sent; logs are sanitized to redact common secrets.

Commands overview

Detailed command documentation lives in docs/commands.md, with workflows in docs/workflows.md. REST usage is documented in docs/rest.md. Plain text input is routed into commands when intent routing is enabled; otherwise it maps to /chat --prompt "<text>".

Intent routing configuration lives in src/main/resources/application.properties:

assistant.intent.enabled=true
assistant.intent.model=${embabel.models.llms.cheapest}
assistant.intent.fallback-model=${embabel.models.default-llm}
assistant.intent.temperature=0.1
assistant.intent.max-tokens=256
assistant.intent.allowed-commands=/chat,/plan,/review,/edit,/apply,/run,/gitapply,/git-push,/search
assistant.intent.destructive-commands=/edit,/apply,/run,/gitapply,/git-push
assistant.intent.confidence-threshold=0.8

• /chat: Send prompts. Options: --persona, --session, --model, --temperature, --review-temperature, --max-tokens, --system-prompt.
• /config: Update session settings (auto-paste, local-only, web-search, intent routing).
• /plan: Generate a numbered plan of CLI commands. Options: --persona, --session, --model, --temperature, --review-temperature, --max-tokens, --system-prompt.
• /route: Preview intent routing output without executing commands.
• /intent-debug: Print routing JSON and planned commands without executing.
• /review: Review code with structured Findings/Tests output. Options: --paths, --staged, --min-severity, --no-color, --log-review, --security, --sast, plus model/temperature overrides.
• /reviewlog: Show recent review entries. Options: --min-severity, --path-filter, --limit, --page, --since, --no-color.
• /search: Web search through the agent tool. Options: --limit, --provider, --timeout-millis, --headless, --enable-web-search.
• /codesearch: Ripgrep-backed repo search. Options: --paths, --context, --limit, --pack, --max-chars, --max-tokens.
• /compact: Summarize and compact conversation history to free up context space. Options: --session. Also triggers automatically once context usage crosses a threshold (see Configuration below).
• /edit: Open $EDITOR to draft prompts. Options: --seed, --send, --session, --persona.
• /paste: Paste multiline input (end with /end). Options: --content, --end-marker, --send, --session, --persona.
• /status: Git status. Options: --short-format.
• /diff: Git diff. Options: --staged, --context, --paths, --stat.
• /gitapply: Apply a patch via git. Options: --patch-file, --cached, --check, --confirm.
• /stage: Stage files or hunks. Options: --paths, --file, --hunks, --confirm.
• /commit-suggest: Draft a commit message. Options: --session, --model, --temperature, --max-tokens, --hint, --secret-scan, --allow-secrets.
• /help: Show available slash commands and /config options.
• /git-push: Push with confirmation. Options: --force.
• /model: List or set models. Options: --list, --set, --session.
• /health: Check Ollama connectivity.
• /benchmark: Measure raw Ollama tokens per second. Options: --model, --prompt, --prompt-file, --max-tokens (default 200), --session.
• /!: Execute a shell command directly (alias: /sh). Output streams live and a summary is added to the session context.
• /run: Execute a command with timeout and truncation. Options: --timeout-millis, --max-output-chars, --confirm, --agent-requested.
• /apply: Apply unified diff patches. Options: --patch-file, --dry-run, --confirm.
• /applyBlocks: Apply Search-and-Replace blocks. Options: --blocks, --blocks-file, --dry-run, --confirm.
• /revert: Restore from the latest patch backup. Options: --dry-run.
• /context: Show targeted edit context. Options: --start, --end, --symbol, --padding.
• /tree: Show repository tree (respects .gitignore). Options: --depth, --dirs-only, --max-entries.

Running from source

1. Install Java 21 and maven 3.9.9 or later
2. Start Ollama and pull the models with ./models.sh, including nomic-embed-text:latest. Embabel validates embedding model roles at startup, so this model is required even when memory is disabled. This requirement also applies to earlier Embabel versions.
3. Start the interactive shell: ./run.sh. The script builds the jar with Maven and launches it with the JLine REPL and Embabel agents loaded.

Desktop GUI (lcaGui)

A Swing-based desktop UI is available as an alternative to the interactive shell — see docs/gui.md for the design rationale. It's disabled by default (lca.gui.enabled=false in application.properties).

Launch it with:

lca gui

This works with the lca launcher from Launcher script (lca) above, or from a source build — it resolves/downloads the jar, ensures the required Ollama models are installed, and launches with lca.gui.enabled=true (REPL disabled). Building from source, ./localInstall.sh also installs a standalone lcaGui wrapper script — equivalent to lca gui — alongside lca in ~/.local/bin.

Running from source without either script installed, pass the property directly instead:

./run.sh --lca.gui.enabled=true

The GUI shows the base directory, current git branch (with an open PR number alongside it, when one exists), and the active main/small models in a header strip, plus context/memory usage in a footer strip, with the conversation in between.

Quickstart examples

Full end-to-end flows are in docs/quickstart.md.

Edit flow:

/context --file-path src/main/groovy/se/alipsa/lca/shell/ShellCommands.groovy \
  --symbol review
/chat --prompt "Update the review output header to include timestamps."
/applyBlocks --file-path src/main/groovy/se/alipsa/lca/shell/ShellCommands.groovy \
  --blocks "<blocks>"

Review flow:

/review --paths src/main/groovy --prompt "Look for error handling and logging gaps"
/reviewlog --min-severity MEDIUM --limit 3

Plan flow:

/plan --prompt "Review src/main/groovy and suggest improvements"

Search + git flow:

/codesearch --query "applyPatch" --paths src/main/groovy
/diff --staged
/stage --paths src/main/groovy/se/alipsa/lca/shell/ShellCommands.groovy
/commit-suggest --hint "UX polish"

Batch mode

Run one or more commands non-interactively and exit when done.

Inline command string:

java -jar local-coding-assistant-<version>.jar \
  -c "/status; /review --paths src/main/groovy; /commit-suggest"

Batch file (one command per line; each line can include ;-separated commands):

java -jar local-coding-assistant-<version>.jar --batch-file scripts/batch.txt

Notes:

• Exit code is 0 when all commands succeed, non-zero on the first failure.
• Use --yes (or --assume-yes) to auto-confirm destructive prompts in CI; leave it off by default.
• Add --batch-json to emit a JSON summary line per command for machine parsing.
• Batch mode uses the same configuration files, workspace root, and safety limits as interactive mode.
• Commands run relative to the working directory where java -jar starts; if that is not a git repo, git commands report that git is unavailable.

Roadmap focus

• Rich editing and review loops driven from the CLI.
• Code search and repository-aware context with git operations.
• Opinionated prompts and workflows tuned for local development sessions.

License

MIT License. See LICENSE for details.