# CLAUDE.md
## Project Overview
`upsync` is a Rust CLI tool that ports projects between programming languages and keeps ports synchronized with upstream changes using AI coding agents.
## Architecture
```
src/
├── main.rs # CLI entry point, command handlers (port, init, check, sync)
├── config.rs # Configuration and state file management (YAML/JSON)
├── agents.rs # AI agent abstraction (Claude, Gemini, Codex)
├── git.rs # Git operations (clone, fetch, diff, language detection)
└── prompts.rs # Prompt templates for port and sync operations
```
## Key Commands
| `port` | Create new port from upstream URL to target language |
| `init` | Initialize tracking for existing manually-ported project |
| `check` | Fetch upstream and report changes since last sync |
| `sync` | Apply upstream changes to the ported codebase |
## Development
```bash
cargo build # Build
cargo run -- --help # Run with args
cargo check # Type check
```
## File Conventions
- `upstream-sync.yml` - User config (upstream URL, agent preference, verify command)
- `.upstream-sync/state.json` - Sync state (last commit, languages)
- `.upstream-cache/` - Cloned upstream repository
## Agent Invocation
Agents are invoked via CLI with restricted tool access:
```
claude -p "<prompt>" --allowedTools Edit,Write,Bash,Read,Glob,Grep
```
The `invoke_with_retry` function runs verification after each attempt and retries with error context on failure (max 3 attempts).
## Adding New Commands
1. Add variant to `Commands` enum in `main.rs`
2. Add match arm in `main()` function
3. Implement `cmd_<name>()` handler function
## Adding New Languages
Update `detect_language()` in `git.rs` to map file extensions to language names, and optionally add a default verify command in `config.rs`.