mixseek-debug

MixSeek Debugging Features

Overview

MixSeek-Plus provides multiple debugging environment variables. By using these, you can enable detailed log output during agent execution and perform problem diagnosis and behavior verification.

Environment Variable List

Environment Variable	Value	Effect	Scope
`MIXSEEK_VERBOSE`	`1` or `true`	Integrated debug mode	MCP tool logs + `mixseek.member_agents`(DEBUG) + `claudecode_model`(DEBUG)
`CLAUDECODE_MODEL_LOG_LEVEL`	`DEBUG`	Logs for claudecode-model alone	claudecode-model package only
`MIXSEEK_LOGFIRE`	`1` or `true`	Logfire instrumentation	pydantic-ai tracing (requires Logfire configuration)

Recommended Settings

For normal debugging, MIXSEEK_VERBOSE=1 alone is sufficient.

MIXSEEK_VERBOSE=1 When set, the following logs are enabled:

MCP tool call start/completion logs
mixseek.member_agents DEBUG-level output for the logger
claudecode_model DEBUG-level output for the logger

Usage

Step 1: Check Environment Variables

To check the current environment variable settings, run the following script:

bash skills/mixseek-debug/scripts/check-debug-env.sh

Step 2: Usage When Running the CLI

Method A: Set environment variables and run the CLI

# 統合デバッグモード（推奨）
MIXSEEK_VERBOSE=1 uv run mskp team "タスク" --config configs/agents/team.toml

# claudecode-model単体のデバッグ
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml

# 複数の環境変数を組み合わせ
MIXSEEK_VERBOSE=1 MIXSEEK_LOGFIRE=1 uv run mskp team "タスク" --config configs/agents/team.toml

Method B: Set for the entire shell session

# 現在のセッションに設定
export MIXSEEK_VERBOSE=1

# 以降のコマンドはすべてverboseモードで実行される
uv run mskp team "タスク" --config configs/agents/team.toml

# 無効化
unset MIXSEEK_VERBOSE

Step 3: Usage with the Python API

import mixseek_plus

# 方法A: enable_verbose_mode()を使用（推奨）
mixseek_plus.enable_verbose_mode()
mixseek_plus.patch_core()

# これ以降のClaudeCodeエージェントはverboseログを出力
# コンソール出力例:
# [Tool Start] fetch_page: url=https://example.com
# [Tool Done] fetch_page: success in 1234ms

# ファイル出力先: $WORKSPACE/logs/member-agent-YYYY-MM-DD.log

# verboseモードを無効化
mixseek_plus.disable_verbose_mode()

import os
import mixseek_plus

# 方法B: 環境変数を直接設定
os.environ["MIXSEEK_VERBOSE"] = "1"
mixseek_plus.patch_core()

# 方法C: 一時的に有効化（コンテキストマネージャは非提供、手動管理）
os.environ["MIXSEEK_VERBOSE"] = "1"
try:
    # デバッグしたい処理
    pass
finally:
    del os.environ["MIXSEEK_VERBOSE"]

Log Output Destinations

Console Output

MIXSEEK_VERBOSE=1 When enabled, output to the console in the following format:

[Tool Start] <tool_name>: <params>
[Tool Done] <tool_name>: <status> in <time>ms
[Tool Result Preview] <result_preview>

Example:

[Tool Start] fetch_page: url=https://example.com/docs
[Tool Done] fetch_page: success in 2345ms
[Tool Result Preview] # Documentation\n\nWelcome to...

File Output

Member Agent logs are output to the following files:

$MIXSEEK_WORKSPACE/logs/member-agent-YYYY-MM-DD.log

Output Contents:

Tool call details (parameters, execution time, status)
Agent execution trace information
Errors and stack traces

claudecode_model logs

MIXSEEK_VERBOSE=1 When enabled, theclaudecode_model logger is also automatically set to DEBUG level, and the following is output:

claudecode_model - DEBUG - <message>

Combination Examples

1. Basic Debugging (Most Common)

MIXSEEK_VERBOSE=1 uv run mskp team "Webページを取得して要約して" --config configs/agents/team.toml

2. Add Logfire Tracing

# 事前にLogfireの設定が必要
MIXSEEK_VERBOSE=1 MIXSEEK_LOGFIRE=1 uv run mskp team "タスク" --config configs/agents/team.toml

3. Debugging claudecode-model Alone

If you want to suppress other logs and debug only claudecode-model:

CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml

Troubleshooting

No Logs Are Output

Cause 1: Environment variables are not set correctly

# 確認
echo $MIXSEEK_VERBOSE

# 正しく設定
export MIXSEEK_VERBOSE=1

Cause 2: patch_core() is not called

When using the Python API,patch_core() must be called:

import mixseek_plus
mixseek_plus.enable_verbose_mode()
mixseek_plus.patch_core()  # これを忘れないこと

Cause 3: No log handler is configured

Check the Python logging configuration:

import logging
logging.basicConfig(level=logging.DEBUG)

File Logs Cannot Be Found

Cause: MIXSEEK_WORKSPACE is not set

# 確認
echo $MIXSEEK_WORKSPACE

# 設定
export MIXSEEK_WORKSPACE=/path/to/workspace

# ログファイルの場所
ls -la $MIXSEEK_WORKSPACE/logs/

Too Much Log Output

MIXSEEK_VERBOSE=1 outputs a lot of logs. If you want to debug only a specific component:

# claudecode-model単体のみ
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml

Alternatively, control logger levels individually in Python:

import logging

# 特定のロガーのみDEBUGに
logging.getLogger("claudecode_model").setLevel(logging.DEBUG)

# 他はINFOに抑制
logging.getLogger("mixseek.member_agents").setLevel(logging.INFO)

Logfire traces are not displayed

Cause: Logfire is not configured

To use Logfire, configuration is required in advance:

import logfire
logfire.configure()

For details, see Logfire official documentation .

Next steps

Once debugging is complete, remove or disable the environment variable:

unset MIXSEEK_VERBOSE
unset CLAUDECODE_MODEL_LOG_LEVEL
unset MIXSEEK_LOGFIRE

Or, with the Python API:

import mixseek_plus
mixseek_plus.disable_verbose_mode()

About this skill