lcode-cli 0.1.1__tar.gz

lcode_cli-0.1.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json,md}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

lcode_cli-0.1.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @nasser1941

lcode_cli-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: Something doesn't work as documented.
+labels: [bug, triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please check the [troubleshooting guide](https://nasser1941.github.io/lcode/troubleshooting/) first.
+        **Don't paste secrets, tokens or private code.**
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What you did, what you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. lcode --model qwen3.5-9b
+        2. Ask "..."
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `lcode doctor`
+      description: Shows your lcode, Ollama and model versions and your hardware.
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Ubuntu / Debian
+        - Other Linux
+        - macOS (Apple Silicon)
+        - Windows (WSL2)
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output or logs
+      description: Terminal output, or Ollama server logs (`journalctl -u ollama` on Linux, `~/.ollama/logs/server.log` on macOS).
+      render: text

lcode_cli-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://nasser1941.github.io/lcode/
+    about: Installation, models, configuration and troubleshooting.
+  - name: Questions and ideas
+    url: https://github.com/nasser1941/lcode/discussions
+    about: Ask questions and share what you built in GitHub Discussions.
+  - name: Report a security vulnerability
+    url: https://github.com/nasser1941/lcode/security/advisories/new
+    about: Please report security issues privately, not as public issues.

lcode_cli-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest an idea or improvement.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the situation where lcode falls short today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd like to work on this myself

lcode_cli-0.1.1/.github/ISSUE_TEMPLATE/model_request.yml

@@ -0,0 +1,42 @@
+name: Model request or test report
+description: Ask for a model to be added to the catalog, or report how a model runs on your hardware.
+labels: [models]
+body:
+  - type: markdown
+    attributes:
+      value: Real-world results decide which models lcode recommends, so reports are very welcome.
+  - type: input
+    id: tag
+    attributes:
+      label: Ollama tag
+      placeholder: e.g. qwen3.5:9b
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Type
+      options:
+        - Please add this model to the catalog
+        - Test report for a catalog model
+    validations:
+      required: true
+  - type: input
+    id: hardware
+    attributes:
+      label: Hardware
+      placeholder: e.g. RTX 4070 12 GB + 32 GB RAM, or MacBook Pro M4 Pro 48 GB
+    validations:
+      required: true
+  - type: textarea
+    id: results
+    attributes:
+      label: Results
+      description: Context size used, tokens/s, whether tool calls (reading, editing, running commands) worked reliably, and anything odd.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `lcode doctor`
+      render: text

lcode_cli-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What does this change?
+
+<!-- A short description, and the issue it closes (e.g. "Closes #12"). -->
+
+## How was it tested?
+
+<!-- Tests added, commands run, and for model changes: hardware, context size, tokens/s and a real task you tried. -->
+
+## Checklist
+
+- [ ] `uv run pytest` and `uv run ruff check .` pass
+- [ ] Tests cover the change
+- [ ] Docs and `CHANGELOG.md` (*Unreleased*) are updated for user-facing changes
+- [ ] No secrets, tokens, personal paths or private data are included

lcode_cli-0.1.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

lcode_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev ruff format --check .
+      - name: Shellcheck install.sh
+        run: shellcheck install.sh
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run --group dev pytest
+
+  build:
+    name: Build package and docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv build
+      - name: Check the wheel ships the model catalog
+        run: unzip -l dist/*.whl | grep -q "lcode/models.toml"
+      - run: uv run --group docs mkdocs build --strict

lcode_cli-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv run --group docs mkdocs build --strict
+      - name: Publish the installer next to the site
+        run: cp install.sh site/install.sh
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

lcode_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published, using PyPI Trusted Publishing:
+# no API token is stored anywhere. PyPI must list this repository, this workflow file and the
+# "pypi" environment as a trusted publisher for the lcode-cli project.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/lcode-cli/
+    permissions:
+      id-token: write # to prove to PyPI that the upload comes from this workflow
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check the release tag matches the package version
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/lcode/__init__.py)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::Release tag $GITHUB_REF_NAME does not match package version $version"
+            exit 1
+          fi
+      - run: uv build
+      - name: Smoke-test the wheel
+        run: uvx --from dist/*.whl lcode --version
+      - run: uv publish --trusted-publishing always

lcode_cli-0.1.1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Docs build output
+site/
+
+# Editors and OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Secrets and local settings: never commit these
+.env
+.env.*
+*.pem
+*.key

lcode_cli-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+# Install with: uvx pre-commit install
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        args: [--unsafe] # mkdocs.yml uses custom tags
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-added-large-files
+      - id: detect-private-key
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks

lcode_cli-0.1.1/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Guidance for coding agents (including lcode itself) working on this repository.
+
+## Overview
+
+lcode is a terminal coding agent that runs open-weight models locally through Ollama. Python 3.10+,
+packaged with hatchling, managed with uv. Runtime dependencies: requests, rich, prompt_toolkit
+(and tomli on Python 3.10).
+
+## Commands
+
+```bash
+uv sync --group dev                 # set up .venv
+uv run pytest                       # tests (no Ollama needed)
+uv run ruff check . && uv run ruff format --check .
+uv run --group docs mkdocs build --strict   # docs
+uv run lcode doctor                 # check a local install against a running Ollama
+```
+
+## Architecture
+
+- `src/lcode/cli.py` — entry point `lcode.cli:main`; chat by default, subcommands `setup`, `models`,
+  `doctor`, `config`. Resolves catalog keys to installed Ollama models (`resolve_model`) and picks
+  the context window (`choose_context`).
+- `src/lcode/repl.py` — prompt_toolkit session, slash commands (`handle_command`), status bar.
+- `src/lcode/agent.py` — `Agent.run_turn` loop: stream a response (`assistant_step`), run tool calls,
+  append `role: tool` messages, repeat. Also system prompt, sessions and compaction.
+- `src/lcode/tools.py` — tool JSON schemas (`SCHEMAS`) and implementations (`Toolbox.t_<name>`).
+  Tools return strings; errors start with `Error:` and never raise into the loop.
+- `src/lcode/catalog.py` + `src/lcode/models.toml` — model specs and memory estimates;
+  `src/lcode/hardware.py` detects NVIDIA VRAM or Apple unified memory.
+
+## Conventions
+
+- Line length 120, ruff rules in `pyproject.toml`. Keep modules dependency-light.
+- User-facing text: plain, specific, and actionable (say what to run to fix a problem).
+- Every behavior change needs a test; use `FakeOllama` and the `make_agent` fixture from
+  `tests/conftest.py` to script model responses.
+- Update `docs/` and `CHANGELOG.md` (*Unreleased*) for user-facing changes.
+- Never commit secrets, personal paths or real user data.

lcode_cli-0.1.1/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to lcode are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-28
+
+### Added
+
+- `qwen3.5-9b` and `qwen3.5-4b` are now tested end to end, with measured speed and memory on a 12 GB
+  GPU in the docs. `lcode setup` now recommends only tested models on common machines.
+- Social preview image for the repository and link previews for the docs site.
+- Release workflow that publishes to PyPI with Trusted Publishing.
+
+### Changed
+
+- Memory estimates use ~1 GB of runtime overhead instead of 1.5 GB, matching measurements, so small
+  models get larger context windows (e.g. `qwen3.5-9b` at 128K on a 12 GB GPU).
+
+### Fixed
+
+- `lcode --model X` no longer reuses the context window saved for the default model; it picks the
+  largest window that fits X. `/model` does the same inside a session.
+- `lcode models` fits in 80-column terminals.
+
+## [0.1.0] - 2026-09-28
+
+First public release.
+
+### Added
+
+- Interactive terminal agent with streaming markdown output, reasoning display, `@file` attachments,
+  slash commands, a status bar and resumable sessions (`lcode -c`).
+- One-shot mode for scripts: `lcode -p "..."`.
+- Tools for the model: `read_file`, `write_file`, `edit_file` (with diff previews and a
+  whitespace-tolerant fallback), `list_dir`, `glob`, `grep` (ripgrep with a pure-Python fallback),
+  `bash` (live output, timeouts, persistent working directory) and `todo_write`.
+- Permission modes `ask`, `auto-edit` and `yolo` (Shift+Tab cycles), with a read-only command
+  allowlist and "always allow" per command.
+- Model catalog with eight open-weight models, hardware detection for Linux + NVIDIA and Apple
+  Silicon Macs, and memory-fit estimates that pick the largest context window that fits.
+- `lcode setup` (recommend, download and configure a model), `lcode models`, `lcode doctor` and
+  `lcode config`.
+- Choice of context window per run (`--context 128k`), per session (`/ctx`) or in the config file.
+- Text-only model variants that drop unused vision projectors to free GPU memory.
+- Automatic conversation compaction when the context window is 85% full, plus `/compact`.
+- `AGENTS.md` project instructions and `/init` to generate them.
+- One-line installer for Linux and macOS.
+
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/nasser1941/lcode/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/nasser1941/lcode/releases/tag/v0.1.0

lcode_cli-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement (currently the
+maintainer, [@nasser1941](https://github.com/nasser1941)) by email at
+[nasser_derakhshan@yahoo.com](mailto:nasser_derakhshan@yahoo.com), privately through
+[this confidential report form](https://github.com/nasser1941/lcode/security/advisories/new),
+or with GitHub's "Report content" option on the comment.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.