.suzi Directory

The ~/.suzi/ directory is the Suzi CLI's local data store. It's created automatically the first time you run suzi login and contains authentication tokens, configuration, caches, installed skills, and AI session history.

~/.suzi/
├── config.json          # Auth tokens, user info, account selection, preferences
├── sessions.json        # AI coding session history and deployment records
├── history.json         # Sanitized CLI command history
├── actions-cache.json   # Cached protocol actions with JSON schemas
├── skills-cache.json    # Cached skills manifest from registry
└── skills/              # Canonical installed Suzi skills

config.json

Primary configuration file. Stores authentication credentials, service URLs, account data, and user preferences.

{
  "apiUrl": "https://api-3ihwe.ondigitalocean.app",
  "webUrl": "https://new.suzi.trade",
  "defaultAi": "claude",
  "accessToken": "<JWT>",
  "refreshToken": "<JWT>",
  "user": {
    "id": "uuid",
    "email": "you@example.com",
    "privyUserId": "privy:xxx"
  },
  "activeAccountId": "uuid",
  "accounts": [
    {
      "id": "uuid",
      "name": "My Account",
      "svmWalletAddress": "So1...",
      "evmWalletAddress": "0x..."
    }
  ],
  "preferences": {
    "username": "alice",
    "toolingOnboarding": {
      "codexInstallSkippedAt": "2026-03-01T00:00:00Z",
      "claudeCodexMcpConfiguredAt": "2026-03-01T00:00:00Z",
      "neverRemindCodex": false
    }
  }
}

Field reference

What writes to it

• suzi login — stores tokens, user info, and accounts after OAuth
• suzi accounts — updates activeAccountId
• suzi preferences — updates apiUrl and username
• suzi start --set-default ... — updates defaultAi
• Token refresh — silently updates accessToken and refreshToken on expiry

sessions.json

Tracks AI coding sessions started with suzi start, resumed with suzi resume, and any agents deployed during those sessions.

{
  "version": "1.0.0",
  "sessions": [
    {
      "sessionId": "abc-123",
      "createdAt": "2026-03-23T10:00:00Z",
      "projectPath": "/Users/you/my-agent",
      "projectName": "my-agent",
      "aiProvider": "claude",
      "model": "claude-opus-4-6",
      "deployments": [
        {
          "agentId": "uuid",
          "deployedAt": "2026-03-23T10:05:00Z",
          "title": "Market Watcher"
        }
      ]
    }
  ]
}

Retention

• Maximum 200 sessions are retained.
• Sessions older than 90 days are eligible for cleanup.
• When the limit is exceeded, the oldest sessions are trimmed automatically.

history.json

A sanitized log of CLI commands you've run, including execution status and duration. Used by suzi feedback to automatically include recent context when reporting issues.

[
  {
    "command": "run",
    "args": ["polymarket.deposit", "--amount", "1"],
    "status": "success",
    "durationMs": 1240,
    "timestamp": "2026-03-23T10:00:00Z"
  },
  {
    "command": "login",
    "args": [],
    "status": "error",
    "durationMs": 3500,
    "errorOutput": "Network timeout after 3000ms",
    "timestamp": "2026-03-23T09:55:00Z"
  }
]

Sanitization

Arguments containing sensitive keywords (token, key, secret, password, auth, credentials, private) are automatically redacted. JWT tokens are replaced with <TOKEN>.

Retention

• Maximum 100 entries. Oldest entries are removed when the limit is exceeded.
• Error messages are truncated to 500 characters.

actions-cache.json

Locally cached list of all available protocol actions and their JSON schemas. This avoids a network call on every command that needs to look up an action.

{
  "fetchedAt": 1711180800000,
  "actions": [
    {
      "name": "place_order",
      "protocol": "polymarket",
      "description": "Place an order on a Polymarket market",
      "requires": { "wallet": ["evm"] },
      "parameters": { "...JSON Schema..." },
      "response": { "...JSON Schema..." }
    }
  ]
}

Cache behavior

• TTL: 5 minutes. After expiry, the next command that needs actions will re-fetch from the API.
• Force refresh: Run suzi list-actions reload to bypass the cache and pull fresh data.
• Failure handling: Cache write failures are silently ignored — a missing or corrupt cache file simply triggers a fresh fetch.

When to clear

Delete this file (or run suzi list-actions reload) if:

• You see stale or missing actions after a platform update
• A new protocol was added and actions aren't showing up
• Action parameter schemas seem outdated

skills-cache.json

Cached skills manifest downloaded from the Suzi registry. Skills are embedded content bundles (typically markdown and code) used for local AI assistant integrations.

{
  "fetchedAt": 1711180800000,
  "contentHash": "a1b2c3d4",
  "skills": [
    {
      "name": "long-running-agents",
      "description": "Guide for building robust, long-running agents",
      "files": [
        {
          "path": "guide.md",
          "content": "..."
        }
      ]
    }
  ]
}

Cache behavior

• TTL: 60 minutes.
• Content hash: A checksum of skill content, used to detect changes.
• Force refresh: Run suzi skills sync to bypass the cache and pull the latest skills.

When to clear

Delete this file (or run suzi skills sync) if:

• Skills appear outdated or incomplete
• You've been told new skills are available but don't see them
• Skill installation fails with unexpected content

skills/

~/.suzi/skills/ is the canonical Suzi skill store.

When you run suzi login, suzi skills add, or suzi skills sync, the CLI writes skill files here first and then links them into supported local clients such as:

• ~/.claude/skills
• ~/.codex/skills
• ~/.agents/skills

This avoids drift between clients and replaces the older model where each client had its own independent installed copy.

Safe to delete?

Yes. Deleting ~/.suzi/skills/ removes the canonical installed skills. Run suzi skills sync to rebuild it and relink clients.

Troubleshooting

Reset authentication

If you're getting auth errors or need to switch users:

# Option 1: Log out cleanly (clears tokens, user, and account data)
suzi logout

# Option 2: Manually remove tokens from config.json
# Edit ~/.suzi/config.json and delete accessToken and refreshToken fields

Clear caches

# Refresh actions cache
suzi list-actions reload

# Refresh skills cache and relink installed skills
suzi skills sync

# Or delete cache files directly
rm ~/.suzi/actions-cache.json
rm ~/.suzi/skills-cache.json

What's safe to delete

Nuclear reset

To completely reset the CLI to a fresh state:

rm -rf ~/.suzi
suzi login

This removes all local data and requires you to re-authenticate. Caches will rebuild on first use.