OpenCode + Neovim + tmux : le setup complet

Mise à jour juillet 2026 — OpenCode n’est plus mon agent quotidien (retour à Claude Code, documenté dans Anthropic, le Apple de l’IA). Ce guide reste valide pour un setup OpenCode, et les patterns transférables — AGENTS.md par dossier, bibliothèque de commands versionnée — valent pour n’importe quel agent.

OpenCode est un agent de coding construit pour le terminal. Son architecture client/serveur en Go et son TUI vim-like en font l’outil le plus naturel pour un workflow Neovim/tmux — le seul qui ne demande pas de compromis sur ta façon de travailler.

Ce guide documente le setup que j’utilise quotidiennement : Mac en local, Ubuntu en remote via SSH, Neovim + tmux comme environnement de travail, OpenCode dans un split dédié.

Comment installer OpenCode ?

L’installation est un binaire unique. Pas de node_modules, pas de runtime Python, pas d’extension IDE.

# Installation via le script officiel
curl -fsSL https://opencode.ai/install | bash

# Vérification
opencode --version

# Sur Ubuntu/Debian en remote — même commande
# Le binaire va dans ~/.local/bin/ ou /usr/local/bin/

Si tu préfères ne pas piper dans bash, les binaires sont disponibles directement sur GitHub Releases pour Linux AMD64, ARM64, macOS Intel et Apple Silicon.

Comment configurer les providers LLM ?

OpenCode utilise un fichier de configuration JSON. La première chose à faire est de définir au minimum un provider avec sa clé API.

// ~/.config/opencode/config.json
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  },
  "model": "anthropic/claude-sonnet-4-5",
  "theme": "dark"
}

OpenRouter est intéressant à configurer en parallèle : il donne accès à Gemini Flash, MiniMax et des dizaines d’autres modèles via une seule clé API. Changer de modèle devient alors une question de secondes.

Note (à l’époque où j’utilisais ce setup) : Kilo Code CLI — un fork d’OpenCode — propose aussi Kilo Gateway, qui donne accès à des modèles gratuits (dont MiniMax 2.5). Une alternative intéressante si tu veux réduire les coûts à zéro sur les tâches mécaniques — setup abandonné depuis, voir l’encadré en tête de guide.

# Changer de modèle depuis OpenCode / Kilo Code CLI
# Dans le TUI : appuyer sur 'm' pour ouvrir le sélecteur de modèles
# Ou directement :
opencode --model openrouter/google/gemini-2.0-flash-001

Pour un projet spécifique, tu peux surcharger la config globale avec un fichier local :

// monprojet/.opencode/config.json
{
  "model": "openrouter/google/gemini-2.0-flash-001"
}

Ce fichier local est commité dans Git — toute l’équipe utilise le même modèle par défaut sur ce projet.

Comment intégrer OpenCode dans tmux ?

L’intégration tmux est simple et donne un résultat très naturel. L’idée : un split vertical permanent, Neovim à gauche, OpenCode à droite.

Layout de base :

# Depuis n'importe quelle session tmux
# Créer un split vertical et lancer OpenCode
tmux split-window -h -l 40% 'opencode'

# Ou via un binding tmux dans ~/.tmux.conf
bind-key a split-window -h -l 40% 'opencode'

Configuration tmux recommandée pour ce workflow :

# ~/.tmux.conf — extraits pertinents

# Préfixe plus accessible
set -g prefix C-a
unbind C-b

# Navigation entre panneaux vim-style
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Lancer OpenCode dans un split droit
bind-key a split-window -h -l 38% 'opencode'

# Lancer une nouvelle session OpenCode nommée (pour remote)
bind-key A new-session -d -s opencode 'opencode' \; switch-client -t opencode

# Redimensionnement rapide
bind-key -r H resize-pane -L 3
bind-key -r L resize-pane -R 3

Pour un setup remote SSH :

# Sur le serveur remote — démarrer OpenCode dans une session tmux persistante
tmux new-session -d -s oc 'opencode'

# Depuis ta machine locale
ssh user@serveur -t 'tmux attach -t oc'

# Si la session n'existe pas encore
ssh user@serveur -t 'tmux new-session -A -s oc opencode'

La session survit aux déconnexions SSH. Tu retrouves ton agent exactement où tu l’avais laissé.

Comment configurer le fichier de contexte projet ?

Un fichier AGENTS.md (ou CLAUDE.md) à la racine du projet est lu automatiquement par OpenCode au démarrage de chaque session. C’est la mémoire permanente de l’agent sur ton projet.

# AGENTS.md — monprojet

## Stack
- PHP 8.3 · Symfony 7.1 · API Platform 3
- TypeScript 5 · React 18 · Vite 5
- Tests : PHPUnit 11 (backend) · Vitest (frontend)
- DB : PostgreSQL 16

## Conventions critiques
- Les services Symfony sont `final` par défaut
- Les repositories héritent de `AbstractRepository`
- Tests : `AbstractServiceTest` pour les services, `AbstractApiResourceTest` 
  pour les endpoints
- Pas de logique dans les constructeurs

## Ce que l'agent NE fait PAS sans demander
- Modifier une interface publique de service existant
- Créer des migrations Doctrine
- Modifier les fichiers de config Symfony (`services.yaml`, `security.yaml`)

## Commandes utiles
- Tests backend : `php bin/phpunit --filter NomDuTest`
- Tests frontend : `npx vitest run`
- TypeScript check : `npx tsc --noEmit`
- Serveur dev : `symfony serve -d`

Pour des conventions spécifiques à un sous-répertoire, un AGENTS.md local est lu en plus du fichier racine :

# src/Service/AGENTS.md
- Services : final, injection constructeur uniquement
- Méthodes publiques > 20 lignes → à découper
- Pas de dépendance directe sur les Repositories depuis les Services
  (passer par des interfaces)

Comment créer des custom commands ?

Les custom commands sont le mécanisme le plus puissant d’OpenCode pour capitaliser les workflows récurrents. Ce sont des fichiers Markdown dans .opencode/commands/, versionnés dans Git.

mkdir -p .opencode/commands

Exemple — créer un endpoint API Platform complet :

# .opencode/commands/new-endpoint.md

Crée un endpoint API Platform 3 complet pour l'entité `$ARGUMENTS`.

Fichiers à créer :
1. `src/ApiResource/{Entity}Resource.php`
   - Opérations : GetCollection, Get, Post, Patch, Delete
   - Groups : `{entity}:read`, `{entity}:write`

2. `tests/ApiResource/{Entity}ResourceTest.php`
   - Étend AbstractApiResourceTest
   - Couvre : liste, détail, création valide/invalide, update, delete

3. `tests/fixtures/{Entity}Fixtures.php`

Lance ensuite : `php bin/phpunit tests/ApiResource/{Entity}ResourceTest.php`
Corrige les erreurs jusqu'à ce que les tests passent.

Utilisation :

> /new-endpoint Order

Autres commands utiles à créer selon ton projet :

.opencode/commands/
├── new-endpoint.md        # Endpoint API Platform complet
├── new-service.md         # Service Symfony avec tests
├── review-pr.md           # Revue de code avec checklist
├── write-tests.md         # Tests pour un fichier existant
└── explain-error.md       # Analyse d'un stack trace

Quels sont les keymaps essentiels du TUI ?

OpenCode a une navigation vim-like. Les essentiels pour être productif dès le premier jour :

Raccourci	Action
i ou Entrée	Passer en mode insertion (écrire)
Échap	Quitter le mode insertion
j / k	Naviguer dans l’historique
/	Chercher dans la conversation
m	Ouvrir le sélecteur de modèles
n	Nouvelle session
q	Quitter
/add chemin/fichier	Ajouter un fichier au contexte
/clear	Vider le contexte de la session

Pour ajouter des fichiers au contexte — le plus utilisé :

> /add src/Service/OrderService.php
> /add tests/Service/OrderServiceTest.php

Ce que ça change dans le workflow quotidien

Après plusieurs mois avec ce setup, les habitudes qui se sont installées :

Un split tmux dédié à l’agent tourne en permanence pendant les sessions de code. Neovim à gauche, agent à droite. Quand une tâche se présente, je la brief sans quitter Neovim. L’agent lit les fichiers, produit le code, je reviens dans Neovim pour la review.

Les custom commands couvrent maintenant ~70% des tâches récurrentes sur le projet Symfony. Créer un endpoint, écrire les tests d’un service, analyser un stack trace — ce sont des commandes, pas des instructions reconstituées à chaque fois.

Le switch de modèle selon la tâche était devenu un réflexe sur ce setup : tâche mécanique (tests boilerplate, migration) → modèle budget ou gratuit via Kilo Gateway, tâche de raisonnement (architecture, debugging complexe) → Claude Sonnet. L’écosystème OpenCode/Kilo Code CLI permettait ce routing sans friction.

Ressources

• OpenCode — documentation officielle
• OpenCode — dépôt GitHub
• OpenRouter — accès multi-provider
• Guide : Gérer le contexte dans un workflow multi-agents
• Guide : Principes du workflow agentique