Fenn — local-code-agent

Un agent de code en ligne de commande, open-source, conçu d'abord pour tourner avec des LLM locaux (LM Studio, Ollama, ou tout endpoint compatible OpenAI) — sans abonnement, sans service opéré par le projet. Un mode clé API est aussi supporté : c'est votre clé, vous la gérez et la payez vous-même, le projet ne s'en sert jamais.

Fenn lit et modifie du code dans un dépôt cible, exécute des commandes shell, et vérifie automatiquement ses propres modifications — le tout piloté par un modèle de langage que vous choisissez. La localisation exacte de symboles (find_symbol) et les résumés de contexte fonctionnent sur JavaScript/TypeScript (React, Next.js compris), Python, Go et Rust ; les autres langages restent utilisables (lecture/écriture/shell), juste sans cette précision-là.

État du projet : jeune, en développement actif. Voir ROADMAP.md pour ce qui reste à faire avant une version stable.

Documentation complète : source dans docs/ (site Next.js/Nextra), déployée séparément — l'URL sera ajoutée ici une fois le site en ligne.

Installation

npm install -g @abhidaksh/fenn

Ou en développement, sans build :

npm run dev   # équivalent à `agent`, via tsx

Démarrage rapide — modèle local

1. Lancez un serveur compatible OpenAI en local : LM Studio ou Ollama (mode API OpenAI), avec un modèle chargé.
2. Dans le dépôt que vous voulez que Fenn modifie :

   agent

   Par défaut, Fenn cherche un serveur sur http://localhost:1234/v1 (le port par défaut de LM Studio). Changez de modèle à tout moment avec /model <nom>, ou pointez vers un autre endpoint avec /baseurl <url>.

Démarrage rapide — clé API

export AGENT_LLM_BASE_URL="https://api.votre-fournisseur.com/v1"
export AGENT_LLM_API_KEY="votre-clé"
export AGENT_LLM_MODEL="nom-du-modèle"
agent

Tout endpoint compatible OpenAI Chat Completions fonctionne (OpenAI, Anthropic via son endpoint de compatibilité, etc.). La clé n'est jamais persistée sur disque par /apikey — seulement /model et /baseurl s'écrivent dans .agentrc.json si vous le confirmez.

Utilisation

agent                        # mode session interactif (persiste modèle/historique entre tâches)
agent run "<instruction>"    # tâche ponctuelle
agent scan <chemin>          # génère un CONTEXT.md par dossier source
agent ping "<message>"       # test rapide de connectivité au modèle configuré

Flags utiles pour agent run : --no-context, --no-plan, --no-git, --plain (sortie texte simple au lieu du TUI), --verbose, --yolo (ignore toutes les confirmations — à réserver à un environnement de confiance).

Évaluer un modèle

npm run eval

Rejoue un petit jeu de tâches fixes contre le modèle actuellement configuré (local ou API), dans des dépôts jetables — jamais ce dépôt-ci. Utile pour comparer la fiabilité de plusieurs modèles locaux sur des tâches réalistes avant de choisir lequel utiliser au quotidien. Voir eval/ et CLAUDE.md pour le détail.

En mode session, /help liste les commandes disponibles (/model, /baseurl, /apikey, /mcp, /settings, /usage, /clear, /exit). Shift+Tab bascule le "mode auto" (plus aucune confirmation demandée pendant la tâche en cours) ; Échap interrompt la tâche en cours.

Configuration

Ordre de priorité : variables d'environnement > .agentrc.json (racine du dépôt cible) > ~/.local-code-agent/config.json > valeurs par défaut.

| Variable | Rôle | |---|---| | AGENT_LLM_BASE_URL | Endpoint compatible OpenAI (défaut : http://localhost:1234/v1) | | AGENT_LLM_API_KEY | Clé API, jamais écrite sur disque | | AGENT_LLM_MODEL | Nom du modèle à utiliser | | AGENT_MAX_ITERATIONS | Plafond d'appels au modèle par étape de plan (défaut : 10) | | AGENT_VERIFY_COMMAND | Commande de vérification à lancer une fois par étape après une écriture | | AGENT_SHELL_SANDBOX | require | allow-fallback (défaut) | off — voir "Modèle de sécurité" | | AGENT_SHELL_SANDBOX_NETWORK | deny (défaut) | allow — accès réseau du sous-processus confiné | | AGENT_CONTEXT_WINDOW_TOKENS | Force la taille de fenêtre de contexte utilisée pour dimensionner les lectures/mémoire, au lieu de la détection automatique |

Sans AGENT_VERIFY_COMMAND, Fenn détecte automatiquement une commande de vérification : npm test si package.json a un script test, sinon npx tsc --noEmit si un tsconfig.json existe, sinon la vérification est désactivée.

Fenn essaie aussi de dimensionner les lectures de fichiers et la mémoire inter-étapes sur la vraie taille de contexte du modèle plutôt que sur des valeurs fixes pensées pour un petit modèle local : pour LM Studio/Ollama, en interrogeant l'API du serveur ; pour un modèle cloud connu (Claude, GPT-4o, GPT-4.1...), via une estimation basée sur son nom. AGENT_CONTEXT_WINDOW_TOKENS force une valeur si la détection échoue ou se trompe.

Modèle de sécurité

Fenn peut lire, écrire et exécuter des commandes dans le dépôt cible sur simple demande en langage naturel — voici les garanties qui existent aujourd'hui, et leurs limites connues :

• Confinement au dépôt. Toute opération fichier/commande résout ses chemins par rapport au dépôt cible, jamais en dehors.
• Confirmation par défaut. Toute commande shell ou action potentiellement destructive demande confirmation, sauf ce que vous avez explicitement approuvé "toujours" pour la session, ou en --yolo.
• Blocklist sur les commandes shell. sudo, les installeurs de paquets système/globaux (apt, brew, pip install, npm install -g...) sont bloqués sans confirmation possible — combiné à la confirmation systématique sur tout le reste (une commande composée ne peut pas se faire passer pour une commande simple et sûre).
• Confinement réel du sous-processus run_shell (au-delà de la confirmation). En plus de la confirmation humaine, le sous-processus shell est lancé sous un confinement système quand un mécanisme est disponible : sandbox-exec (Seatbelt) sur macOS, bwrap (bubblewrap) sur Linux — écriture disque limitée au dépôt cible (+ /tmp), accès réseau refusé par défaut (configurable via AGENT_SHELL_SANDBOX_NETWORK). AGENT_SHELL_SANDBOX=require refuse d'exécuter la commande plutôt que de la lancer sans confinement si le mécanisme n'est pas disponible ; le défaut (allow-fallback) exécute quand même, avec un avertissement explicite. Limites connues : Windows n'a aucun mécanisme de confinement (avertissement systématique, mode require toujours refusé) ; la lecture n'est pas confinée (seule l'écriture l'est) ; ceci reste une seconde couche de défense, pas un remplacement de la confirmation humaine — voir ROADMAP.md et src/agent/sandbox.ts pour le détail par plateforme.
• Snapshots git automatiques. Si le dépôt cible est sous git, un commit de sauvegarde est créé avant chaque étape d'un plan, avec proposition de rollback en cas d'échec.
• Vérification après écriture. La commande de vérification configurée tourne après chaque write_file réussi ; 3 échecs consécutifs font échouer l'étape.
• Le .agentrc.json d'un dépôt cible n'est pas fiable par défaut. Il peut arriver via un git clone, pas forcément écrit par vous. Si celui du dépôt que vous ouvrez configure des serveurs MCP, un baseURL différent, ou affaiblit le sandbox run_shell, Fenn vous le signale explicitement et demande confirmation avant d'appliquer quoi que ce soit — en cas de refus (ou par défaut), ces réglages précis retombent sur leurs valeurs sûres, sans bloquer le reste de la commande. --yolo accepte automatiquement (en l'affichant quand même) plutôt que de le passer sous silence.

Avant toute chose : ne faites tourner Fenn que sur du code sous contrôle de version, et passez en revue ce qu'il fait tant que le projet est jeune.

Contribuer

Pas encore de guide de contribution formalisé — le projet est encore jeune. Voir ROADMAP.md pour l'état d'avancement et ce qui reste à faire avant une sortie stable ; les PR sur ces points sont bienvenues.

Installer depuis les sources

Pour développer sur Fenn lui-même (pas pour l'utiliser au quotidien — voir Installation plus haut pour ça) :

git clone https://github.com/ABHIDAKSH9405/CLI-project.git
cd CLI-project
npm install
npm run build
npm link   # rend la commande `agent` (celle des sources locales) disponible globalement

Site de documentation

Pour travailler sur le site de documentation (docs/, sous-projet séparé avec son propre package.json, jamais inclus dans le paquet npm publié) :

cd docs
npm install
npm run dev       # serveur local avec rechargement à chaud
npm run build     # génère docs/.next

Licence

MIT