qodacode 0.1.0

Hybrid code analysis tool with AI-powered explanations

Qodacode

Mejores prácticas enforced automáticamente con memoria persistente del proyecto.

Qué es

Qodacode es una herramienta híbrida que combina:

• Motor nativo (determinístico): Detecta issues en el código usando análisis estático
• IA (Claude): Interpreta los resultados y explica al dev dónde está la causa

No compite con Claude Code. Lo complementa.

Por qué existe Qodacode

Limitaciones de Claude Code que Qodacode resuelve

Claude Code puede...	Pero no puede...	Qodacode resuelve
Detectar issues cuando se lo pides	Hacerlo siempre automáticamente	Watch mode continuo
Leer archivos que le indicas	Conocer TODO el repo siempre	Memoria persistente
Encontrar problemas en el momento	Recordar mañana qué revisó	Historial de análisis
Analizar archivos individuales	Detectar conflictos cross-file	Contexto completo
Reaccionar a pedidos	Ser proactivo	Alertas automáticas

Lo que Claude Code hace bien (y no reemplazamos)

• Generar código rápido
• Resolver problemas
• Iterar features
• Explicar código

Lo que Qodacode agrega

• Verificación continua automática
• Memoria persistente del proyecto
• Detección cross-file
• Mejores prácticas enforced sin pedirlo

Para quién es

Segmento	Dolor que resuelve
Vibe coders con IA	"¿Mi código generado está bien?"
Devs tradicionales	"¿Mi código cumple mejores prácticas?"
Equipos mixtos	"¿El código del equipo es consistente?"
Freelancers	"¿Puedo entregar esto a un cliente enterprise?"

Funciona igual para código generado por IA o código escrito manualmente. El origen no importa.

El problema

Escribes código (con IA o manual)
         ↓
Funciona en local
         ↓
¿Está listo para producción? ← No hay respuesta clara
         ↓
Rezas y deployeas

La solución

Motor nativo detecta issues (determinístico, sin alucinaciones)
         ↓
Produce resultado estructurado (JSON)
         ↓
IA interpreta con contexto completo del proyecto
         ↓
Dev recibe explicación clara de qué y dónde arreglar

Qué detecta

Seguridad

• Secrets en código
• SQL/Command injection
• XSS
• Endpoints sin auth
• CVEs en dependencias

Robustez

• Sin error handling en llamadas externas
• Sin timeouts
• Sin retry logic
• Race conditions

Mantenibilidad

• Duplicación entre archivos
• Funciones >200 líneas
• Imports circulares
• Dead code

Operabilidad

• Sin logging en flujos críticos
• Config hardcodeada
• Sin health checks
• Dockerfile mal configurado

Comandos CLI

qodacode init      # Indexa el repo (memoria persistente)
qodacode watch     # Monitoreo continuo (background)
qodacode check     # Check on-demand
qodacode status    # Estado actual
qodacode doctor    # Verificar engines instalados

Instalación

pip install qodacode

Engines Opcionales

Qodacode tiene un motor nativo (Tree-sitter) que siempre funciona. Para análisis más profundo, puedes instalar engines opcionales:

Engine	Comando	Función
Semgrep	pip install semgrep	SAST profundo (--deep)
Gitleaks	brew install gitleaks	Detección de secretos (--secrets)
OSV	(API, requiere internet)	CVEs en dependencias (--deps)

Verifica qué tienes instalado con:

qodacode doctor

Uso en CI/CD

Para pipelines automatizados, usa --skip-missing para evitar prompts interactivos:

qodacode check --all --skip-missing

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                      QODACODE                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  PARSING                                                │
│  └─ Tree-sitter (multi-lenguaje, AST)                  │
│                                                         │
│  DETECCIÓN (Motor Nativo)                               │
│  └─ Reglas determinísticas                              │
│  └─ Análisis estático                                   │
│  └─ Output estructurado (JSON)                          │
│                                                         │
│  MEMORIA PERSISTENTE                                    │
│  └─ Embeddings offline (nomic-embed)                   │
│  └─ Vector DB local (Chroma en .qodacode/)             │
│  └─ Contexto cross-file                                 │
│                                                         │
│  INTEGRACIÓN IA                                         │
│  └─ MCP Server para Claude Code                         │
│  └─ Recibe issues + contexto                            │
│  └─ Explica al dev en lenguaje natural                  │
│                                                         │
│  ✓ 100% local, nada sale de tu máquina                 │
│  ✓ IA opcional, solo para explicar                      │
└─────────────────────────────────────────────────────────┘

Flujo híbrido

[Motor nativo detecta]
{
  "file": "src/api/payments.py",
  "line": 142,
  "rule": "no-rate-limit",
  "severity": "critical"
}

[IA responde al dev]
"Tu endpoint de pagos en payments.py:142 no tiene
rate limiting. Como este archivo maneja transacciones
y está expuesto públicamente (vi en routes.py:23),
un atacante podría hacer requests masivos. Agrega
rate limiting antes del handler."

Diferenciadores

Característica	Qodacode	Linters tradicionales
Memoria persistente	✓ Conoce todo el repo	✗ Olvida entre corridas
Contexto cross-file	✓ Detecta relaciones	✗ Archivo por archivo
Explicación contextual	✓ IA explica el por qué	✗ Solo muestra el error
Solo issues críticos	✓ Lo que importa	✗ 500 warnings genéricos
100% local	✓ Nada sale	Varía

Stack técnico

• Lenguaje: Python
• Parsing: Tree-sitter (multi-lenguaje)
• Embeddings: nomic-embed (offline)
• Vector DB: Chroma (local, en .qodacode/)
• Integración IA: MCP Server para Claude Code

Lenguajes soportados

• MVP: Python + TypeScript/JavaScript
• v1.0: Go, Rust, Java

Integraciones

• CLI
• VSCode/Cursor extension
• MCP Server (Claude Code)
• GitHub Actions (gate para PRs)
• Pre-commit hook

Estructura del proyecto

qodacode/
├── qodacode/
│   ├── __init__.py
│   ├── cli.py           # Comandos: init, check, watch, status, why
│   ├── scanner.py       # Parsea código con tree-sitter
│   ├── rules/           # Reglas de detección
│   │   ├── __init__.py
│   │   ├── security.py  # Secrets, injection, XSS
│   │   ├── robustness.py # Error handling, timeouts
│   │   ├── maintainability.py # Duplicación, funciones largas
│   │   └── operability.py # Logging, health checks
│   ├── memory/          # Embeddings + vector DB
│   │   ├── __init__.py
│   │   ├── indexer.py   # Indexa el repo
│   │   └── store.py     # Chroma vector store
│   ├── reporter.py      # Output estructurado
│   └── mcp/             # MCP Server para Claude
│       ├── __init__.py
│       └── server.py
├── tests/
├── pyproject.toml
└── README.md

Output ejemplo

$ qodacode check

ISSUES DETECTADOS (3)

CRÍTICO src/api/payments.py:142
  Regla: no-rate-limit
  → Endpoint público sin rate limiting

CRÍTICO src/config/settings.py:23
  Regla: hardcoded-secret
  → Secret hardcodeado: DATABASE_URL

ALTO src/services/user.py:89
  Regla: unsanitized-input
  → Input no sanitizado en query SQL

───────────────────────────
Usa 'qodacode why <file>' para explicación detallada con IA

Roadmap

Fase	Qué
MVP	CLI + 15-20 reglas críticas + memoria básica
v0.2	Watch mode + más reglas
v0.3	MCP Server (integración Claude Code)
v0.4	VSCode/Cursor extension
v1.0	Multi-lenguaje completo + CI/CD gates

Open Source a estudiar (no copiar, extraer patrones)

El desarrollo se acelera estudiando estos proyectos para entender arquitecturas y patrones:

Análisis Estático (Detección)

Proyecto	Qué estudiar	URL
Semgrep	Cómo estructurar reglas YAML, motor de pattern matching	https://github.com/semgrep/semgrep
Bandit	Checks de seguridad para Python	https://github.com/PyCQA/bandit
Ruff	Velocidad extrema en análisis, arquitectura Rust	https://github.com/astral-sh/ruff
Tree-sitter	Parsing multi-lenguaje, AST	https://github.com/tree-sitter/tree-sitter

Memoria / RAG para Código

Proyecto	Qué estudiar	URL
Code-Graph-RAG	Indexación de código + knowledge graphs	https://github.com/vitali87/code-graph-rag
Code Knowledge MCP	Patrón de MCP Server con memoria	https://glama.ai/mcp/servers/@davidvc/code-knowledge-mcptool
Mem0	Memoria persistente para IA	https://github.com/mem0ai/mem0
RAGFlow	Motor RAG open source	https://github.com/infiniflow/ragflow

Embeddings (Offline)

Modelo	Qué estudiar	URL
nomic-embed	Embeddings offline, ligero, local	https://huggingface.co/nomic-ai/nomic-embed-text-v1.5
Qwen3-Embedding	Soporte código, Apache 2.0	https://huggingface.co/Qwen
E5 models	Alta precisión, rápido	https://huggingface.co/intfloat

Vector DB

Proyecto	Qué estudiar	URL
Chroma	Vector DB embebido, Python native	https://github.com/chroma-core/chroma
FAISS	Vector search de Facebook, performance	https://github.com/facebookresearch/faiss
LanceDB	Embebido, rápido	https://github.com/lancedb/lancedb

Enfoque

Open source = Estudiar cómo lo hicieron
                    ↓
            Extraer patrones y arquitectura
                    ↓
            Crear código propio de Qodacode
                    ↓
            Producto original, desarrollo acelerado

No copiamos código. Aprendemos arquitecturas y creamos el nuestro.

Principios

1. Detección nativa, explicación con IA - Lo mejor de ambos mundos
2. Solo issues que importan - No 500 warnings, solo lo crítico
3. Memoria persistente - Conoce todo el proyecto, siempre
4. 100% local - Privacidad total, nada sale de tu máquina
5. Parte del workflow - No un paso extra, siempre presente

Por qué no muere en meses

Los productos que sobreviven resuelven dolor diario. Qodacode:

1. Se integra donde vive el dev - Cursor, VSCode, Claude Code, terminal
2. No es un paso extra - Watch mode corre en background
3. Siempre relevante - Mientras escribas código, Qodacode es útil
4. No requiere configuración constante - Init una vez, funciona siempre

El dev nunca piensa en Qodacode.
Qodacode siempre está pensando en el código del dev.

Modelo de negocio

Gratis (siempre)

• CLI completo
• Todas las reglas de detección
• Memoria persistente local
• Uso ilimitado

Pro ($19/mes)

• Watch mode continuo
• Integración CI/CD
• Análisis automático de PRs
• Soporte prioritario

Team ($49/mes por dev)

• Reglas custom compartidas
• Dashboard de equipo
• Métricas históricas
• Onboarding dedicado

Competencia y diferenciación

Herramienta	Debilidad	Qodacode gana porque
SonarQube	Pesado, cloud, caro	100% local, ligero, freemium
Semgrep	Solo SAST, sin memoria	Memoria persistente + contexto
Snyk	Solo seguridad, cloud	Mejores prácticas completas + local
Bandit	Solo Python, básico	Multi-lenguaje + explicación IA
Linters	500 warnings, sin contexto	Solo lo crítico + cross-file

Nadie combina: Análisis estático + memoria persistente + explicación con IA + 100% local.

Flujo de trabajo diario

Mañana:
  └─ Abres Cursor
  └─ Qodacode ya indexó cambios nocturnos (watch)
  └─ Ves: "2 issues nuevos desde ayer"

Mientras codeas:
  └─ Escribes código
  └─ Qodacode detecta issue en background
  └─ Notificación: "src/api.py:45 - sin error handling"
  └─ Arreglas en el momento

Antes de commit:
  └─ Pre-commit hook corre qodacode check
  └─ Si hay críticos, bloquea commit
  └─ Arreglas y commiteas limpio

En PR:
  └─ GitHub Action corre qodacode
  └─ Comenta issues en el PR
  └─ Gate: no merge si hay críticos

---

Qodacode: Mejores prácticas enforced. Siempre. Automático. Sin pensarlo.