REST API: Diagnostic Mode

Endpoint: `POST /api/diagnostic/run`

Ten endpoint uruchamia Claude Code w trybie diagnostyczno-naprawczym z pełnymi uprawnieniami do zarządzania środowiskiem Dockera.

Różnice vs normalna sesja

Normalna sesja (/cg:new):

Claude Code działa WEWNĄTRZ kontenera Docker
Ograniczony do workspace w kontenerze
Nie może zarządzać kontenerami z góry

Tryb diagnostyczny (ten endpoint):

Claude Code działa BEZPOŚREDNIO na hoście
Pełny dostęp do Docker (może zabijać/restartować kontenery)
Uruchamiany z flagą --permission-mode bypassPermissions
Może diagnozować i naprawiać problemy z infrastrukturą

Request

json

POST /api/diagnostic/run
Content-Type: application/json

{
  "channel_name": "frontend-dev",
  "workspace_path": "/var/lib/docker/codegen/workspaces/frontend-dev",
  "prompt": "Frontend nie startuje, sprawdź logi dockera i napraw problem",
  "callback_url": "http://mattermost.example.com/webhook/diagnostic-result",
  "model": "sonnet"
}

Parametry

Parametr	Typ	Wymagany	Opis
`channel_name`	string	✅ Tak	Nazwa kanału Mattermost (identyfikator sesji)
`workspace_path`	string	✅ Tak	Pełna ścieżka do workspace gdzie ma działać Claude
`prompt`	string	✅ Tak	Zadanie dla Claude - co ma zdiagnozować/naprawić
`callback_url`	string	❌ Nie	URL gdzie zostanie wysłany wynik po zakończeniu (webhook)
`model`	string	❌ Nie	Model AI: `"sonnet"` (default) lub `"opus"`

Response

Sukces (200 OK)

json

{
  "message": "Diagnostic session started",
  "channel_name": "frontend-dev",
  "workspace_path": "/var/lib/docker/codegen/workspaces/frontend-dev",
  "model": "sonnet",
  "log_path": "/path/to/logs/diagnostic-frontend-dev-20250203-143022.log",
  "callback_url": "http://mattermost.example.com/webhook/diagnostic-result"
}

Błąd (400 Bad Request)

json

{
  "error": "workspace path does not exist: /invalid/path"
}

json

{
  "error": "channel_name, workspace_path and prompt are required"
}

Callback Response

Gdy sesja diagnostyczna się zakończy, system automatycznie wyśle POST request na callback_url (jeśli został podany).

Format callback payload:

json

POST {callback_url}
Content-Type: application/json

{
  "channel_name": "frontend-dev",
  "success": true,
  "error": "",
  "response": "Znalazłem problem: port 3000 jest zajęty przez inny proces.\n\nNaprawiłem to przez:\n1. Zabicie procesu na porcie 3000\n2. Restart kontenera frontend\n3. Weryfikacja że wszystko działa poprawnie\n\nFrontend teraz działa pod http://localhost:3000",
  "log_path": "/path/to/logs/diagnostic-frontend-dev-20250203-143022.log",
  "duration_seconds": 127,
  "completed_at": "2025-02-03T14:32:29Z"
}

Pola callback response:

Pole	Typ	Opis
`channel_name`	string	Nazwa kanału Mattermost (identyfikator sesji)
`success`	boolean	`true` jeśli sesja zakończyła się sukcesem, `false` jeśli wystąpił błąd
`error`	string	Komunikat błędu (pusty string jeśli sukces)
`response`	string	Pełna odpowiedź Claude'a - wszystkie wiadomości połączone w jeden tekst
`log_path`	string	Ścieżka do pliku logu sesji diagnostycznej
`duration_seconds`	integer	Czas trwania sesji w sekundach
`completed_at`	string	Timestamp zakończenia w formacie ISO 8601 (RFC3339)

Przykład błędu w callback:

json

{
  "channel_name": "frontend-dev",
  "success": false,
  "error": "exit status 1",
  "response": "",
  "log_path": "/path/to/logs/diagnostic-frontend-dev-20250203-143022.log",
  "duration_seconds": 5,
  "completed_at": "2025-02-03T14:30:27Z"
}

Przykłady użycia

1. Diagnoza problemu z frontendem (z callback)

bash

curl -X POST http://localhost:9090/api/diagnostic/run \
  -H "Content-Type: application/json" \
  -d '{
    "channel_name": "frontend-dev",
    "workspace_path": "/var/lib/docker/codegen/workspaces/frontend-dev",
    "prompt": "Frontend nie startuje. Sprawdź logi dockera, zidentyfikuj problem i napraw go.",
    "callback_url": "http://mattermost.example.com/webhook/diagnostic-result",
    "model": "sonnet"
  }'

2. Restart dockerów z diagnozą

bash

curl -X POST http://localhost:9090/api/diagnostic/run \
  -H "Content-Type: application/json" \
  -d '{
    "channel_name": "backend-api",
    "workspace_path": "/var/lib/docker/codegen/workspaces/backend-api",
    "prompt": "Kontenery nie działają poprawnie. Zatrzymaj wszystkie kontenery, wyczyść stare obrazy, zrestartuj docker-compose i upewnij się że wszystko działa.",
    "callback_url": "http://mattermost.example.com/webhook/diagnostic-result",
    "model": "opus"
  }'

3. Analiza wydajności (bez callback)

bash

curl -X POST http://localhost:9090/api/diagnostic/run \
  -H "Content-Type: application/json" \
  -d '{
    "channel_name": "performance-test",
    "workspace_path": "/var/lib/docker/codegen/workspaces/performance-test",
    "prompt": "Aplikacja działa wolno. Przeanalizuj logi wszystkich kontenerów, sprawdź wykorzystanie zasobów (CPU, RAM, dysk) i zidentyfikuj bottleneck.",
    "model": "opus"
  }'

Uwaga: Jeśli nie podasz callback_url, wyniki będą dostępne tylko w pliku logu.

Logi sesji diagnostycznej

Każda sesja diagnostyczna tworzy unikalny plik logu w katalogu:

/path/to/manager/logs/diagnostic-{channel_name}-YYYYMMDD-HHMMSS.log

Format nazwy: diagnostic-frontend-dev-20250203-143022.log

Zawartość logu:

[DIAGNOSTIC] Session started at 2025-02-03T14:30:22Z
[DIAGNOSTIC] Channel: frontend-dev
[DIAGNOSTIC] Command: cd /workspace && CLAUDE_CODE_OAUTH_TOKEN=... claude ...
[DIAGNOSTIC] Prompt: Frontend nie startuje, sprawdź logi dockera i napraw problem
[DIAGNOSTIC] Callback URL: http://mattermost.example.com/webhook/diagnostic-result

[DIAGNOSTIC] Process started with PID: 12345
[STDERR] Loading Claude Code...
[OUTPUT] {"type":"assistant_message","content":"Sprawdzam logi dockera..."}
[CLAUDE] Sprawdzam logi dockera...
[OUTPUT] {"type":"assistant_message","content":"Znalazłem błąd: port 3000 jest zajęty"}
[CLAUDE] Znalazłem błąd: port 3000 jest zajęty
...
[DIAGNOSTIC] Process completed successfully
[DIAGNOSTIC] Session ended at 2025-02-03T14:35:18Z
[DIAGNOSTIC] Duration: 4m56s

Uprawnienia Claude w trybie diagnostycznym

Claude Code uruchamiany przez ten endpoint ma dostęp do:

✅ Pełne uprawnienia:

Docker management: docker ps, docker stop, docker compose up/down
Filesystem: Odczyt/zapis plików na hoście
Bash commands: Wszystkie komendy systemowe
Process management: Może zabijać i restartować procesy
Network: Pełny dostęp do sieci

🔧 Typowe operacje:

Zatrzymanie/restart kontenerów Docker
Czyszczenie obrazów i wolumenów
Analiza logów z wszystkich kontenerów
Modyfikacja docker-compose.yml
Diagnoza problemów z siecią/portami
Rebuild środowiska od zera

Best Practices

✅ DO:

Używaj tego endpointu gdy normalna sesja nie może rozwiązać problemu
Podawaj konkretne prompty opisujące problem
Monitoruj logi sesji diagnostycznej
Używaj Opus dla złożonych problemów wymagających głębokiej analizy

❌ DON'T:

Nie używaj dla normalnej pracy deweloperskiej (użyj /cg:new)
Nie uruchamiaj wielu sesji diagnostycznych równolegle na tym samym workspace
Nie podawaj zbyt ogólnych promptów ("napraw wszystko")

Integracja z Mattermost

Ten endpoint może być wywołany przez webhook z Mattermost, np. przez przycisk "🔧 Diagnose & Fix" w kanale.

Flow z callback:

1. User klika przycisk w Mattermost
   ↓
2. Mattermost wysyła webhook do /api/diagnostic/run
   - Zawiera workspace_path, prompt, callback_url
   ↓
3. Manager MM startuje Claude Code na hoście
   - Proces działa w tle
   - Manager MM natychmiast odpowiada "Diagnostic session started"
   ↓
4. Mattermost wyświetla użytkownikowi "🔧 Diagnoza rozpoczęta..."
   ↓
5. Claude Code diagnozuje i naprawia problem
   - Może to trwać kilka minut
   ↓
6. Gdy Claude skończy, Manager MM wysyła POST na callback_url
   - Zawiera pełną odpowiedź Claude'a, success/error, czas trwania
   ↓
7. Mattermost odbiera callback i wyświetla wynik w kanale
   - "✅ Problem naprawiony: Frontend teraz działa"
   - lub "❌ Błąd: nie udało się naprawić"

Przykład implementacji webhook handlera w Mattermost:

javascript

// Endpoint odbierający callback z Manager MM
app.post('/webhook/diagnostic-result', async (req, res) => {
  const { channel_name, success, response, error, duration_seconds, log_path } = req.body;

  // Znajdź ID kanału Mattermost na podstawie channel_name
  const channelId = await getChannelIdByName(channel_name);

  // Wyślij wynik do kanału Mattermost
  if (success) {
    await postToMattermost(channelId, {
      text: `✅ **Diagnostyka zakończona** (${duration_seconds}s)\n\n${response}`,
      attachments: [{
        text: `Logi: ${log_path}`,
        color: 'good'
      }]
    });
  } else {
    await postToMattermost(channelId, {
      text: `❌ **Diagnostyka nie powiodła się**\n\nBłąd: ${error}`,
      attachments: [{
        text: `Logi: ${log_path}`,
        color: 'danger'
      }]
    });
  }

  res.status(200).json({ received: true });
});

← Powrót do dokumentacji

REST API: Diagnostic Mode ​

Endpoint: POST /api/diagnostic/run ​

Różnice vs normalna sesja ​

Request ​

Parametry ​

Response ​

Sukces (200 OK) ​

Błąd (400 Bad Request) ​

Callback Response ​

Format callback payload: ​

Pola callback response: ​

Przykład błędu w callback: ​

Przykłady użycia ​

1. Diagnoza problemu z frontendem (z callback) ​

2. Restart dockerów z diagnozą ​

3. Analiza wydajności (bez callback) ​

Logi sesji diagnostycznej ​

Zawartość logu: ​

Uprawnienia Claude w trybie diagnostycznym ​

✅ Pełne uprawnienia: ​

🔧 Typowe operacje: ​

Best Practices ​

✅ DO: ​

❌ DON'T: ​

Integracja z Mattermost ​

Flow z callback: ​

Przykład implementacji webhook handlera w Mattermost: ​

REST API: Diagnostic Mode

Endpoint: `POST /api/diagnostic/run`

Różnice vs normalna sesja

Request

Parametry

Response

Sukces (200 OK)

Błąd (400 Bad Request)

Callback Response

Format callback payload:

Pola callback response:

Przykład błędu w callback:

Przykłady użycia

1. Diagnoza problemu z frontendem (z callback)

2. Restart dockerów z diagnozą

3. Analiza wydajności (bez callback)

Logi sesji diagnostycznej

Zawartość logu:

Uprawnienia Claude w trybie diagnostycznym

✅ Pełne uprawnienia:

🔧 Typowe operacje:

Best Practices

✅ DO:

❌ DON'T:

Integracja z Mattermost

Flow z callback:

Przykład implementacji webhook handlera w Mattermost: