Guide complet pour installer, configurer et contribuer à My Pixel Company — la plateforme de gestion de workforce IA avec une identité visuelle pixel art rétro.
▶Getting Started
Prérequis
$ node -v$ npm -v$ git --versionbetter-sqlite3 ne supporte pas Node.js 26 (bindings natifs incompilables). Utilisez Node.js ≥ 18 et ≤ 22 — LTS recommandé : Node 20 ou 22. Ajoutez un fichier .nvmrc contenant 20 à la racine pour que nvm/fnm détectent automatiquement la bonne version.# Installer nvm si absent
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Installer et utiliser Node 20 LTS
nvm install 20
nvm use 20
# Vérifier
node -v # doit afficher v20.x.xfnm install 20 && fnm use 20Configuration SSH
ls ~/.ssh/id_*.pubid_ed25519.pub), vous avez déjà une clé — passez à l'étape 3.ssh-keygen -t ed25519 -C "ton@email.com"cat ~/.ssh/id_ed25519.pubssh -T git@gitlab.com
# ou pour GitHub :
ssh -T git@github.comWelcome to GitLab, @username!Installation
# 1. Cloner le dépôt (SSH)
git clone git@gitlab.com:Safronix/my-pixel-company.git
cd my-pixel-company
# 2. Lancer le projet
npm startVariables d'environnement
Démarrage
npm start⬡Stack Technique
Pages dans apps/web/src/app/. Composants dans src/components/. Hooks dans src/hooks/. Auth context dans src/lib/auth.tsx.
Routes dans apps/api/src/routes/. DB queries dans src/db/. Services dans src/services/. Middleware auth dans src/middleware/auth.ts.
Accès synchrone, pas d'ORM. Toutes les queries dans apps/api/src/db/<resource>.ts.
Les agents sont des processus Claude Code CLI spawnés via child_process. Supervisés par l'AgentManager (singleton EventEmitter).
◈Structure du Monorepo
Le projet est organisé en npm workspaces. Un seul npm install à la racine installe tout.
my-pixel-company/
├── apps/
│ ├── api/ # Fastify API (Node.js + TypeScript)
│ │ └── src/
│ │ ├── routes/ # Routes HTTP par ressource
│ │ ├── db/ # Queries SQLite (better-sqlite3)
│ │ ├── services/ # Logique métier
│ │ └── middleware/
│ │ └── auth.ts # Vérification JWT
│ └── web/ # Next.js App Router (TypeScript)
│ └── src/
│ ├── app/ # Pages (App Router)
│ ├── components/ # Composants React
│ ├── hooks/ # Hooks React
│ └── lib/
│ ├── api.ts # Client API centralisé
│ └── auth.tsx # Contexte d'authentification
└── packages/
└── shared/
└── src/
└── types.ts # Types partagés api ↔ webapps/api/src/routes/<resource>.tsHandler HTTP (GET, POST, PUT, DELETE)apps/api/src/db/<resource>.tsQueries SQLite synchronesapps/api/src/services/<resource>.tsLogique métier & orchestrationpackages/shared/src/types.tsTous les types partagés◆Conventions de Code
any. Tous les types partagés dans packages/shared/src/types.ts.// ✓ Correct — type explicite depuis packages/shared
import type { Agent, Task } from '@my-pixel-company/shared'
// ✗ Interdit — any implicite
const data: any = await fetchAgent(id)req.body direct sans schéma.import { z } from 'zod'
const CreateAgentSchema = z.object({
name: z.string().min(1).max(100),
model: z.string(),
provider: z.enum(['anthropic', 'openai']),
})
// Dans la route Fastify
fastify.post('/agents', async (req, reply) => {
const body = CreateAgentSchema.parse(req.body)
// ...
})// Format standard : { error: string, code?: string }
reply.status(404).send({ error: 'Agent not found', code: 'AGENT_NOT_FOUND' })
reply.status(400).send({ error: 'Invalid input' })process.env, ne jamais hardcoder des valeurs sensibles.// ✓ Correct
const jwtSecret = process.env.JWT_SECRET ?? throwMissingEnv('JWT_SECRET')
// ✗ Interdit
const jwtSecret = 'mon-secret-hardcode'Comportement par défaut — réponses structurées, Markdown.
Phrases courtes, directives, sans fioritures. Injecte le bloc CAVEMAN en fin de system prompt.
✦Fonctionnalités
My Pixel Company est une plateforme complète de gestion de workforce IA. Voici les fonctionnalités clés.
Board Kanban avec colonnes personnalisables, drag & drop, commentaires et directives par colonne. Les colonnes peuvent avoir des instructions spécifiques pour guider les agents.
Interface visuelle rétro 2D construite avec Canvas 2D. Visualisez vos agents comme des personnages dans un bureau pixel art.
Chat IA génératif avec streaming temps réel, sessions persistantes et accès complet aux outils MCP.
Créez des tâches récurrentes avec des expressions cron standard pour déclencher des actions automatisées.
Suivez les coûts générés par chaque agent et par projet selon les tokens consommés par provider.
Bibliothèque de compétences assignables aux agents. Repositories Git liés aux projets pour contextualiser le travail.
🔧Troubleshoot — Déblocage d'agent
Procédure à suivre lorsqu'un agent est suspecté d'être bloqué (pas de progression, pas de réponse, tâche en attente depuis trop longtemps).
🔍 1. Détecter le blocage
- ▸Vérifier la dernière activité de l'agent dans le board (colonne, dernière mise à jour)
- ▸Consulter les logs ou outputs de l'agent si disponibles
- ▸Estimer si le silence est anormal selon la complexité de la tâche assignée
🛠️ 2. Demander le déblocage via Claude Code
- 1.Ouvrir une session Claude Code
- 2.Identifier l'agent concerné (nom, projet, tâche assignée)
- 3.Formuler une demande explicite de déblocage en précisant le contexte
- 4.Laisser Claude Code analyser l'état de l'agent et proposer une action corrective
# Lancer Claude Code
claude✅ 3. Vérifier le résultat
- ▸S'assurer que l'agent reprend son activité après intervention
- ▸Si le problème persiste, demander à Claude de faire une analyse plus approfondie pour correction