{"id":50335611,"url":"https://github.com/yuzeguitarist/aitrace","last_synced_at":"2026-05-29T13:30:29.268Z","repository":{"id":355006786,"uuid":"1226400954","full_name":"yuzeguitarist/aitrace","owner":"yuzeguitarist","description":"AI-friendly command-line analyzer for Apple Instruments .trace bundles.","archived":false,"fork":false,"pushed_at":"2026-05-14T04:51:36.000Z","size":76,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T06:43:27.323Z","etag":null,"topics":["agent","ai","ai-tools","cli-tool","instruments","performance-analysis"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuzeguitarist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T10:52:31.000Z","updated_at":"2026-05-14T04:51:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yuzeguitarist/aitrace","commit_stats":null,"previous_names":["yuzeguitarist/aitrace"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yuzeguitarist/aitrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuzeguitarist%2Faitrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuzeguitarist%2Faitrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuzeguitarist%2Faitrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuzeguitarist%2Faitrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuzeguitarist","download_url":"https://codeload.github.com/yuzeguitarist/aitrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuzeguitarist%2Faitrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33655440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-tools","cli-tool","instruments","performance-analysis"],"created_at":"2026-05-29T13:30:28.579Z","updated_at":"2026-05-29T13:30:29.256Z","avatar_url":"https://github.com/yuzeguitarist.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aitrace\n\n`aitrace` is an AI-friendly command-line analyzer for Apple Instruments `.trace`\nbundles. It keeps raw `xctrace` XML out of the model context by turning a trace\ninto a local searchable cache, then printing small deterministic summaries with\nevidence IDs.\n\nThe design goal is not “XML to Markdown”. The design goal is:\n\n```text\n.trace bundle\n  -\u003e xctrace export\n  -\u003e local SQLite + compressed raw evidence\n  -\u003e tiny AI-budget summary\n  -\u003e drill/raw only when the AI needs exact proof\n```\n\n## Status\n\nThis repository contains the first CLI version:\n\n- `aitrace doctor`\n- `aitrace diagnose`\n- `aitrace inspect`\n- `aitrace index`\n- `aitrace summary --preset animation|cpu|cpu-counters|thread-state|ui|poi|diagnostics|energy|hangs|health|memory|oslog`\n- `aitrace find`\n- `aitrace drill`\n- `aitrace raw`\n- `aitrace export` as a debug escape hatch\n\nMCP is intentionally left for a later version.\n\n## Requirements\n\n- macOS\n- Xcode command line tools with `xcrun xctrace`\n\nCheck your machine:\n\n```bash\naitrace doctor\n```\n\n## Install\n\nInstall the latest prebuilt macOS binary from GitHub Releases:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/yuzeguitarist/aitrace/main/install.sh | bash\n```\n\nThe script detects Apple Silicon vs Intel Mac, downloads the matching release\nasset, verifies its checksum when available, and installs `aitrace` into a local\nbin directory. No Rust toolchain or repository clone is required.\n\n## Quick start\n\nStart with a local `.trace` bundle in the current folder, for example\n`Deck.trace`.\n\nPreferred AI one-shot command:\n\n```bash\naitrace diagnose Deck.trace --target Deck --repo . --budget 1800\n```\n\n`diagnose` defaults to `--run latest` so a giant multi-run trace does not\nsilently index every run. It prints compact RCA lines only:\n\n- `rca`: likely root cause in one or two lines\n- `top`: top CPU hotspots\n- `main`: main-thread CPU hotspots\n- `swift`: async/closure/MainActor hints when present\n- `src`: best-effort Swift source file/line hints when `--repo` is provided\n- `ev`: evidence IDs for drill-down\n\nInspect a trace without exporting giant XML into the AI context:\n\n```bash\naitrace inspect Deck.trace --format ai-yaml\n```\n\n`summary`, `find`, `drill`, and `raw` auto-build the cache when needed. Use\ntargeted summaries for follow-up:\n\n```bash\naitrace summary Deck.trace --preset cpu --target Deck --run latest --budget 1200\n```\n\nFor Energy Organizer / Activity Monitor style traces:\n\n```bash\naitrace summary Deck.trace --preset energy --target Deck --run latest --budget 1600\n```\n\nFor Animation Hitches / UI responsiveness traces:\n\n```bash\naitrace summary Deck.trace --preset animation --target Deck --run latest --budget 1200\naitrace summary Deck.trace --preset ui --target Deck --run latest --budget 1200\naitrace summary Deck.trace --preset health --target Deck --run latest --budget 1200\n```\n\nFor CPU Bottlenecks templates that contain CPU Counters, Time Profiler, Thread\nState Trace, and Points of Interest, use separate compact summaries instead of\none giant mixed export:\n\n```bash\naitrace summary Deck.trace --preset cpu --target Deck --run latest --budget 1200\naitrace summary Deck.trace --preset cpu-counters --target Deck --run latest --budget 1200\naitrace summary Deck.trace --preset thread-state --target Deck --run latest --budget 1200\naitrace summary Deck.trace --preset poi --target Deck --run latest --budget 1200\n```\n\nFor Allocations / VM Tracker traces:\n\n```bash\naitrace summary Memory.trace --preset memory --target Deck --run latest --budget 1200\n```\n\nFor mixed system/runtime traces that contain GCD, syscall, thread-state,\nrunloop, region-of-interest, or narrative tables:\n\n```bash\naitrace summary Deck.trace --preset diagnostics --target Deck --run latest --budget 1600\n```\n\nDrill into a finding:\n\n```bash\naitrace drill Deck.trace cpu.hotspot.1 --preset cpu --depth 8 --budget 1000\n```\n\nPrint bounded raw evidence only when necessary:\n\n```bash\naitrace raw Deck.trace ev:cpu:run1:table53:row4428 --context 4 --budget 4000\n```\n\n## AI agent usage rule\n\nPut this in `AGENTS.md` / project instructions for Codex, Claude Code, Cursor,\nor other terminal-using agents:\n\n```md\nWhen analyzing Apple Instruments `.trace` bundles:\n\n1. Do not run `xcrun xctrace` directly, and do not paste exported XML into the\n   model context.\n2. If the environment is unknown, run `aitrace doctor` first.\n3. Start with `aitrace diagnose TRACE.trace --target APP --repo . --budget 1800`.\n   `diagnose` defaults to `--run latest`; use `--run all` only when explicitly\n   needed.\n4. If the trace contents are unknown, run\n   `aitrace inspect TRACE.trace --format ai-yaml`.\n5. Use targeted follow-up summaries, usually with `--run latest`:\n   - `aitrace summary TRACE.trace --preset cpu --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset animation --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset ui --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset cpu-counters --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset thread-state --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset poi --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset diagnostics --target APP --run latest --budget 1600`\n   - `aitrace summary TRACE.trace --preset energy --target APP --run latest --budget 1600`\n   - `aitrace summary TRACE.trace --preset hangs --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset health --target APP --run latest --budget 1200`\n   - `aitrace summary TRACE.trace --preset memory --target APP --run latest --budget 1200`\n6. Use `aitrace find`, `aitrace drill`, and `aitrace raw` only with symbols,\n   finding IDs, or evidence IDs produced by `aitrace`.\n7. Use `aitrace export` only for parser debugging, never as the normal AI loop.\n```\n\n## Cache\n\nBy default, caches live at:\n\n```text\n~/Library/Caches/aitrace\n```\n\nIf that directory is not writable in a sandboxed AI runner, `aitrace` falls back\nto `${TMPDIR}/aitrace-cache`.\n\nOverride with:\n\n```bash\nexport AITRACE_CACHE_DIR=\"$HOME/aitrace-cache\"\n```\n\nThe cache key includes trace metadata, parser version, and the detected\n`xctrace` version. Rebuild explicitly:\n\n```bash\naitrace index Deck.trace --force\n```\n\n## Output contract\n\nIn AI mode (`--format ai-yaml`, the default):\n\n- stdout contains only structured result data\n- `inspect` uses short schema keys (`r`, `i`, `s`, `n`) by default\n- `diagnose` intentionally uses short keys and line strings to minimize tokens\n- `xctrace` stderr is compacted into normalized errors\n- full XML is never printed by `summary`/`find`/`drill`\n- every summary finding contains an `evidence` ID\n- every finding includes a suggested next command\n- `raw` output is budget-limited\n\n## Development\n\nBuild from source:\n\n```bash\ncargo install --path .\n```\n\nRun checks:\n\n```bash\ncargo fmt\ncargo test\ncargo clippy --all-targets -- -D warnings\n```\n\n## Release\n\nCreate and push a version tag:\n\n```bash\ngit tag v0.2.0\ngit push origin v0.2.0\n```\n\nGitHub Actions builds precompiled macOS binaries for Apple Silicon and Intel,\nthen uploads these assets to the GitHub Release:\n\n- `aitrace-aarch64-apple-darwin.tar.gz`\n- `aitrace-x86_64-apple-darwin.tar.gz`\n\nThe parser indexes useful schemas selected from `xctrace export --toc`, stores\nraw table/row evidence compressed, and includes compact schema-aware summaries\nfor Time Profiler, CPU counters, thread state, points of interest, and\nAllocations / VM Tracker statistics.\n\n## License\n\nMIT © 2026 Yuze Pan\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuzeguitarist%2Faitrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuzeguitarist%2Faitrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuzeguitarist%2Faitrace/lists"}