type4me AGENTS.md

Type4Me — Development Guide

Overview

macOS menu bar voice input tool with dual-engine local ASR, multi-provider cloud ASR, and LLM post-processing. Local ASR: SenseVoice via native sherpa-onnx (streaming) + Qwen3-ASR (final calibration, Python WebSocket service managed by SenseVoiceServerManager). Cloud ASR: 14 providers implemented (Volcano, StepFun streaming, StepFun batch, MiMo batch, OpenAI, Deepgram, Cartesia, AssemblyAI, ElevenLabs, Gemini, Grok, Soniox, Bailian, Baidu), plus Apple Speech. Swift Package Manager project, no Xcode project file. Optional sherpa-onnx.xcframework enables local SenseVoice, Silero VAD, and punctuation restoration.

Branch Naming and Lifecycle

Use one short-lived branch for one independently reviewable change. Branches must use lowercase ASCII kebab-case and follow this form:

<type>/<issue-number-optional>-<concise-description>

Examples:

feat/241-cartesia-streaming-asr
fix/247-agent-context-cleanup
docs/intelli-sense-pangu-terminology
perf/reduce-startup-latency
refactor/session-output-pipeline
test/recognition-session-recovery
chore/update-swift-format
release/2.1.1
hotfix/251-crash-on-launch

Allowed types

Type	Use for
feat	A user-visible capability or substantial new behavior.
fix	A defect fix. Prefix the issue number when one exists.
docs	Documentation-only changes.
perf	A measurable performance improvement without a primary behavior change.
refactor	Internal restructuring with no intended behavior change.
test	Test-only additions or repairs.
chore	Tooling, repository maintenance, or non-product housekeeping.
release	Release preparation and versioning.
hotfix	An urgent production fix.

Rules

• Do not use agent, tool, model, or personal prefixes such as agent/, codex/, builder/, or a username. These are execution details, not work categories.
• Do not create a branch named only after a PR number, and do not combine unrelated changes on one branch.
• Keep descriptions specific but compact: prefer fix/247-agent-context-cleanup over fix/247-fix-the-problem-reported-in-the-agent-context-issue.
• Use the same branch name locally and on its published review branch. origin/main is updated only with explicit user authorization.
• Before merging or opening a PR, rebase or otherwise bring the branch up to date with the current origin/main as appropriate for the requested workflow. Use --force-with-lease, never a blind force push, after a published branch is rebased.
• After the change is confirmed in main, delete its local and published remote branches unless there is an explicitly stated reason to retain them. Never delete an integration branch without explicit authorization.
• main is the integration branch. Work directly on it, or push directly to origin/main, only when the user explicitly asks for a direct change.