Siftcode

Local LLM-powered code analysis and developer guide generator.

Siftcode analyzes software projects using a locally-running language model (via Ollama) and produces:

• Per-file summaries — what each file does, its functions, and how it fits
• Per-directory summaries — how files work together
• A comprehensive Markdown developer guide — architecture, setup, API reference, and examples

Everything runs on your own hardware. No code leaves your machine.

---

Why Siftcode?

Reading an unfamiliar codebase is slow. Documentation is often outdated or missing entirely. Existing AI tools send your code to a cloud service, which is a non-starter for proprietary or sensitive projects.

Siftcode combines three things that no other tool offers together:

1. 100 % local — your code never leaves your machine
2. Project-wide context — each file is analyzed with the project's structure and sibling files already in view
3. A cache — re-analysis skips files that haven't changed, making iterative work fast

The result is a well-organized developer guide you can actually use, generated in minutes.

---

Features

• Local-first: runs entirely on your hardware via Ollama
• Cache-aware: unchanged files are never re-analyzed — second runs are up to 10× faster
• Project-wide context: file analyses see the root summary and sibling files, producing coherent guides
• Progress feedback: a live progress bar and log during analysis
• Cancellable: stop an analysis mid-run without losing your work
• Configurable per project: model, context size, temperature, file exclusions, and cache settings are all saved per project
• Two front-ends: a modern GTK4 + libadwaita GUI and a scriptable CLI
• Tested: 200+ unit tests, ~95 % coverage in the core

---

Screenshots

Project list

Settings

Analysis in progress

Generated developer guide

Requirements

• Linux (X11 or Wayland)

• Python 3.11 or newer

• GTK 4.10+ and libadwaita 1.4+

• Ollama running locally

• A code-capable LLM installed via Ollama, for example:

  ollama pull qwen2.5-coder:14b
  

Hardware

Siftcode runs on modest hardware, but quality and speed depend on your GPU and the model you choose.

Model	VRAM (Q4)	~42-file run	Quality	Best for
qwen2.5-coder:7b	~5 GB	~3 min	Basic	Small projects, laptops
qwen2.5-coder:14b	~10 GB	~7 min	Good	Recommended default
qwen2.5-coder:32b	~22 GB	~33 min	Excellent	Workstations, best quality

For CUDA GPUs, ensure your driver is recent enough for your Ollama build. CPU-only operation works but is slow (expect 5–15× longer runs).

Observations from real runs:

• 14B produces a comprehensive guide in ~7 minutes. It occasionally mentions files that don't exist (e.g. setup.py in a modern pyproject.toml project). These are easy to spot and correct.
• 32B is ~4.5× slower but produces a more accurate guide — notably it no longer invents setup.py. However, its output is more concise and may skip smaller files.
• 7B is useful for small projects or when you need a quick pass.

Tip: With 32 GB+ RAM and a workstation-class GPU, you can keep both 14B and 32B loaded at the same time:

export OLLAMA_MAX_LOADED_MODELS=2
export OLLAMA_KV_CACHE_TYPE=q8_0

This lets you use 14B for quick iterations and 32B for the final guide without reloading models from disk.

For CUDA GPUs, ensure your driver is recent enough for your Ollama build. CPU-only operation works but is slow (expect 5–15× longer runs).

Recommended context length

The default num_ctx has been increased from 8192 to 32768 tokens.

Why: The guide generation prompt includes the root summary, all directory summaries, and all file summaries. For a 40-file project, this is roughly 23,000 tokens. With num_ctx=8192, Ollama truncates the context and the model never sees most of the files — the guide ends up mentioning only a handful of modules.

Verification: A real-world 40-file Python project required 23,575 tokens for complete context. With num_ctx=32768, the generated guide mentions 20+ modules including analyzer.py, cache.py, cli.py, and all GUI views.

VRAM: With 14B Q4_K_M + OLLAMA_KV_CACHE_TYPE=q8_0, VRAM usage is ~13 GB. Comfortably within 24 GB.

---

Installation

From source (recommended for now)

git clone https://codeberg.org/lahtis/siftcode.git
cd siftcode
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify installation

siftcode --version
# → siftcode 0.3.0

siftcode about
# → prints version, author, and license

System dependencies (Ubuntu / Debian)

sudo apt install \
    python3-dev python3-gi python3-gi-cairo \
    gir1.2-gtk-4.0 libadwaita-1-0 gir1.2-adw-1 \
    libgirepository1.0-dev libcairo2-dev pkg-config

System dependencies (Fedora)

sudo dnf install \
    python3-devel python3-gobject gtk4 libadwaita \
    gobject-introspection-devel cairo-devel pkg-config

---

Usage

GUI

siftcode-gui

1. Click the + button to add a project directory.
2. Double-click the project to open its settings.
3. Adjust the model, context size, and exclusions if needed.
4. Click Analyze to start.
5. When finished, click Open guide to view the generated Markdown.

CLI

# Register a project under a friendly name
siftcode add /path/to/project --name "My Project"

# List saved projects
siftcode list

# Show a project's configuration
siftcode show "My Project"

# Analyze it (standard run)
siftcode analyze "My Project" --output ~/siftcode-output

# Analyze it with advanced per-file technical specifications
siftcode analyze "My Project" --output ~/siftcode-output --advanced

# Delete a project
siftcode delete "My Project"

The CLI also works without registering:

siftcode analyze /path/to/project --output ./docs

siftcode analyze /path/to/project --output ./docs --advanced

Cache management

siftcode cache stats                # show entry counts and sizes
siftcode cache clear                # remove everything
siftcode cache clear --model qwen2.5-coder:14b
siftcode cache gc --days 30         # prune entries unused for 30 days

Output

Analysis produces two files in the output directory:

• findings.json — raw structured findings (root, directories, files, errors)
• guide.md — the generated developer guide
• docs/specs/ — advanced per-file technical specifications (when --advanced is used)

---

Configuration

Siftcode stores project configurations in the standard XDG config directory:

~/.config/siftcode/projects/<slug>.toml

Each project's TOML file records:

• Project name, path, and notes
• Model name, Ollama URL, context size, temperature, timeout
• File exclusion patterns
• Cache settings
• Last run timestamp

Cache data lives in:

~/.cache/siftcode/

The GUI exposes all of these settings; the TOML file is human-readable and can be edited by hand if you prefer.

---

How it works

1. Root analysis — the LLM sees the project tree and infers the main language(s), purpose, and architecture.
2. File analysis — each file is analyzed with the root summary and the summaries of sibling files already in view.
3. Directory summaries — the LLM summarizes each directory based on the file summaries it contains.
4. Guide generation — all of the above is composed into a structured Markdown developer guide.
5. Advanced specs (optional) — when --advanced is used, individual per-file technical specifications are generated and stored in docs/specs/.

Each step is cached by SHA-256 hash of the input. When you re-run on an unchanged project, only the guide is regenerated.

---

Development

# Clone and install with dev dependencies
git clone https://codeberg.org/lahtis/siftcode.git
cd siftcode
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run the test suite
pytest --cov=siftcode --cov-report=term-missing

# Lint
ruff check src/ tests/

# Type-check
mypy src/

Project layout

siftcode/
├── src/siftcode/
│   ├── _version.py       # single source of truth for metadata
│   ├── cli.py            # command-line interface
│   ├── core/             # framework-agnostic logic
│   │   ├── analyzer.py   # analysis engine
│   │   ├── cache.py      # hash-based cache
│   │   ├── config.py     # project configuration
│   │   ├── llm.py        # Ollama client
│   │   ├── prompts.py    # prompt templates
│   │   └── manual.py     # Advanced Technical Analysis & Specification Generator
│   └── gui/              # GTK4 front-end
│       ├── app.py
│       ├── window.py
│       ├── project_list.py
│       ├── settings_view.py
│       ├── analyzer_view.py
│       └── widgets/
├── tests/                # unit tests
└── pyproject.toml

The core/ package has no GTK dependencies and is usable from any Python program.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Coding style and testing

For translations, open an issue on Codeberg — the string table is not yet extracted, but that will come.

---

License

Siftcode is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE for the full text.

Copyright © 2026 Tuomas Lähteenmäki

---

Acknowledgements

Siftcode stands on the shoulders of excellent open-source projects:

• GTK 4 and libadwaita — the GUI toolkit
• Ollama — local LLM runtime
• Qwen2.5-Coder — the recommended model
• platformdirs — XDG directory handling
• tomli-w — TOML writing

Thank you to the maintainers of these projects.