# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@AGENTS.md

## Commands

```bash
npx expo start          # Start Expo dev server (scan QR with Expo Go)
npx expo start --android
npx expo start --ios
npx expo start --web

eas build --profile preview --platform android   # Build APK via EAS
eas build --profile production --platform android
```

There is no test suite or lint script configured in package.json.

## Architecture

This is an Expo SDK 56 app that monitors AI service usage limits for **Codex CLI** and **Claude.ai**. It fetches usage data from their private REST APIs using credentials the user provides.

### Navigation (Expo Router v3)

```
app/index.tsx              → checks onboarding state, redirects
app/onboarding/            → stack: welcome → codex → claude → done
app/(tabs)/
  _layout.tsx              → bottom tab navigator (4 tabs)
  index.tsx                → Dashboard: both services side-by-side
  codex.tsx                → Codex CLI detailed view
  claude.tsx               → Claude.ai detailed view (not yet in git)
  settings.tsx             → Settings (not yet in git)
```

### Data Flow

Each service follows the same pattern:

1. **Hook** (`hooks/useCodexUsage.ts`, `hooks/useClaudeUsage.ts`) — manages auth + usage state, persists credentials to SecureStore, exposes `refresh()` / `clear()`.
2. **API module** (`lib/api/codexApi.ts`, `lib/api/claudeApi.ts`) — thin fetch wrappers with no side effects.
3. **Screen** — calls the hook, renders `ServiceStatusCard` or the detailed usage UI.

### Credential Storage

All credentials live in `expo-secure-store` (never AsyncStorage). Keys:

- `codex_auth` — serialized `CodexAuth` object (Bearer token + optional account ID), imported from the user's `auth.json` file via `expo-document-picker`.
- `claude_session_key` — cookie value used as `Cookie: sessionKey=…` on claude.ai API calls.

`TOKEN_EXPIRED` errors automatically clear the stored credential and prompt re-entry.

### Styling

NativeWind v4 (Tailwind CSS for React Native). Brand colors:
- Codex: `#10a37f` (teal)
- Claude: `#d97706` (amber)

Use Tailwind utility classes on all components. Dark mode is supported via `dark:` variants.

### Key Types

- `lib/types/codex.ts` — `CodexAuth`, `CodexUsageResponse`, `UsageWindow`
- `lib/types/claude.ts` — `ClaudeOrg`, `ClaudeUsageResponse`, `ClaudeWindowUsage`

### Path Alias

`@/` maps to the repo root (configured in `tsconfig.json`). Use `@/components/...`, `@/lib/...`, `@/hooks/...` everywhere.