Skip to content

AGENTS.md

Latest commit

 

History

History
46 lines (31 loc) · 3.33 KB

AGENTS.md

File metadata and controls

46 lines (31 loc) · 3.33 KB
Raw

Snap-O is a public, open-source Android inspection tool.

Repository Layout

  • app-macos/: macOS app, device transport, and native tests.
  • tools/: Network and Tweaks, each with Android libraries, a frontend, and CLI tests.
  • tool-sdk/: tool plugin authoring APIs, runtime, and Gradle integration.
  • tool-reader/: Android helper used by the macOS app to read tool plugin metadata and frontend assets.
  • device-helper/: session-scoped Android clipboard helper bundled with the macOS app.
  • skills/: installable Network and Tweaks skills, each bundling its standalone Python CLI.
  • examples/: Android demo apps, an independent tool plugin project, and CLI examples.
  • build-logic/ and gradle/: internal Gradle conventions and root build tooling.
  • contracts/: shared protocol definitions and fixtures.
  • docs/: GitHub Pages sources and theme. See docs/README.md for build conventions.

Working Across Components

  • Read the component's AGENTS.md before changing it.
  • Keep macOS ADB and device transport in app-macos/Snap-O/Device/. Keep UI code in the app and tool plugin frontends.
  • Android tool plugins use tool-sdk/core and its ToolServer API. Keep shared socket and HTTP behavior in the core library.
  • Each Python CLI implements its own transport; it does not use the Swift client.
  • When changing shared behavior, check the Android libraries, macOS client, web tool, and both Python CLIs. Use contracts/, its fixtures, and docs/tweaks-protocol.md to keep them compatible.

Test clocks

  • macOS timing tests use the existing continuousClock dependency and TestClock for both time reads and sleeps. See Native test synchronization.
  • Do not add helper framework dependencies or change packaging just to introduce test clocks.
  • Preserve regression coverage when removing sleeps. Do not replace them with deleted tests or extra test time limits; CI already bounds hangs.

Public Repository

Use synthetic data in tests and examples. Never publish credentials, captured private traffic, confidential implementation details, or private issue-tracker links, identifiers, or content. Review the full diff, commit message, and PR text for sensitive information before publishing.

Release readiness

Follow release/README.md when changing protocols, published APIs, version metadata, or packaging. Update release/ checks and tests when protocol definitions or source paths change.

Writing

Use plain technical English in all prose, including READMEs, docs, code comments, UI text, commit messages, and PR descriptions. Prefer common words, active voice, and sentences of about 15 words, with one main idea each. Keep necessary technical terms, explain unfamiliar jargon for the intended reader, and preserve exact meaning. Remove repetition, but do not make the prose choppy or omit useful detail.

Code comments should explain non-obvious reasons or constraints, not repeat what the code does. Before finishing, reread new or changed prose for clarity and accuracy.

Pull Request Descriptions

Lead with a short paragraph explaining the problem, its impact, and why the PR is needed. Put it before ## Summary, without a ## Why heading. Follow the summary with ## Validation, listing the checks performed and any remaining limitations. Keep the description concise and specific.