QAudioAgent

AI-powered workflow agent for Qualcomm Linux audio subsystem feature development and debug, running inside Claude Code.

What it does

Given a plain-English feature description, QAudioAgent automatically:

Identifies the target platform, audio path, codec chain, and ADSP service
Reads the noble kernel source tree to understand existing support and gaps
Drafts a plan broken down by kernel layer — shows it to you for approval
Applies the code changes using domain-specialist subagents
Reviews gates (write-root compliance, contract validity)
Generates a self-contained HTML run report with the full diff embedded

Quick start

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Clone this agent

git clone <this-repo> QAudioAgent
cd QAudioAgent

3. Launch Claude Code inside the agent directory

claude

4. Run a feature

/qaudio-feature-orchestrator feature="add TDM RX DAI link to QCS9100 machine driver for external DAC"

That's it. The agent asks two questions (where is your noble source tree, which commit), then runs the full pipeline automatically.

First-run walkthrough

When you run /qaudio-feature-orchestrator for the first time the agent runs a SETUP phase that asks:

Question 1 — Where is the noble kernel source?

A) Clone it now        ← agent clones to an absolute path you provide
B) I already have it   ← give the absolute path
C) I'm inside it now   ← use current directory

Question 2 — Which commit?

A) Use HEAD as-is      ← default, just press Enter
B) Enter a commit ID   ← e.g. 1d8fb400453c6180582c033c6c47f1b794ad1df3

The clone URL is:

ssh://review-android.quicinc.com:29418/canonical-kernel/ubuntu/source/linux-qcom/noble
branch: clo/canonical/master-next

After SETUP the path is saved to .qaudioagent/config.json — subsequent runs skip SETUP entirely.

Sample run

Request:

/qaudio-feature-orchestrator feature="migrate monaco-addons-monza.dtso from qcs9100 machine driver to sc8280xp machine driver"

What happens:

SETUP    ✓  noble_root=/data/noble  commit=HEAD
CLARIFY  ✓  work_type=port  platform=QCS8300  interface=MI2S  codec=max98091
RESEARCH ✓  9 evidence items · 4 gaps  confidence=high
PLAN     ←  shows you the plan and waits for approval
  [audio_core] audio-core  risk=medium
    sc8280xp.c
      1. Add codec_mclk_enable flag to snd_soc_common struct
      2. Add monaco_gertrude_dapm_widgets[], routes[], controls[]
      3. Add monaco_gertrude_priv_data with codec_dai_fmt[]
      4. Add codec_mclk_enable branch in hw_params()
      ...
    qcs9100.c
      1. Remove monaco_gertrude_* arrays and card struct
      2. Remove strcmp('monaco-gertrude') blocks in hw_params/startup/add_be_ops
      3. Remove compatible entry from dt_match[]
  Proceed? yes
EXECUTE  ✓  sound/soc/qcom/sc8280xp.c  sound/soc/qcom/qcs9100.c
REVIEW   ✓  all gates pass
REPORT   ✓  docs/run_report.html
VALIDATE ⚠  BLOCKED — build and device test not yet run

Open the report:

xdg-open docs/run_report.html

The HTML report contains the full diff, evidence, plan steps, review gates, and validate status — all in one self-contained file you can share.

What works out of the box vs what needs setup

Capability	Status	What's needed
Feature pipeline (CLARIFY→RESEARCH→PLAN→EXECUTE→REVIEW→VALIDATE)	✅ Works	Just the noble kernel source tree
HTML run report with embedded diff	✅ Works	noble source tree (for `git diff`)
Source code navigation (Read, Grep, Glob)	✅ Works	No setup
Audio knowledge wiki (11 seeded pages)	✅ Works	No setup
Debug workflow (`/qaudio-debug`)	✅ Works	Logs on disk
Reset run (`/qaudio-reset-run`)	✅ Works	No setup
Semantic code search (Quartz)	⚙️ Optional	Run `qgenie quartz local <noble_path>` once to index
ADSP log analysis (LogTalk)	⚙️ Optional	Qualcomm SSO login: `qgenie auth logtalk`
Confluence knowledge fallback (qgenie_chat)	⚙️ Optional	Qualcomm SSO login: `qgenie auth qgenie_chat`
CR/FR queries (ODS / Orbit)	⚙️ Optional	Qualcomm SSO login: `qgenie auth ods`
Hardware register lookup (ip_catalog)	⚙️ Optional	Qualcomm SSO login: `qgenie auth ip_catalog`
Gerrit upload (`/qaudio-upload`)	⚙️ Optional	SSH key registered on Gerrit
Build verification (`/qaudio-build`)	⚙️ Optional	Cross-compile toolchain or KAS environment

Minimum requirement: noble kernel source tree. Everything else degrades gracefully — the agent falls back to direct source reads when Quartz is unavailable, and skips Confluence/ODS when not authenticated.

Setting up optional MCPs

All optional MCPs use Qualcomm SSO. Authenticate once per session:

# Semantic code search (strongly recommended — speeds up RESEARCH significantly)
qgenie quartz local /path/to/noble     # build index (~5 min first time)
# Then update .mcp.json quartz-local --repo-path to match

# Log analysis
qgenie auth logtalk

# Confluence knowledge
qgenie auth qgenie_chat

# CR/FR database
qgenie auth ods
qgenie auth orbit

# Hardware IP catalog
qgenie auth ip_catalog

After authentication, re-launch Claude Code — MCPs are loaded at session start.

All skills

Skill	When to use
`/qaudio-feature-orchestrator`	Start here. Full pipeline from one command
`/qaudio-debug`	Diagnose audio failures from logs + source
`/qaudio-build`	Verify the changes compile
`/qaudio-index`	Re-index noble source into Quartz after changes
`/qaudio-cr-query`	List audio CRs by platform or software product
`/qaudio-knowledge`	Query, ingest, or lint the audio wiki
`/qaudio-design-doc`	Regenerate the HTML report from existing phase outputs
`/qaudio-reset-run`	Permanently delete phase outputs for a fresh run
`/qaudio-clarify`	Run CLARIFY phase only
`/qaudio-research`	Run RESEARCH phase only
`/qaudio-plan`	Run PLAN phase only
`/qaudio-execute`	Run EXECUTE phase only
`/qaudio-review`	Run REVIEW phase only
`/qaudio-validate`	Run VALIDATE phase only

Supported platforms

Platform	Codename	Machine driver	Notes
QCS9100	LeMans	`qcs9100.c`	Edge AI — primary target
QCM6490	Kailua	`qcm6490.c`	IoT/QLI 2.0, LPASS macros
SC7280	—	`sc7280.c`	Chromebook
SC8280XP	—	`sc8280xp.c`	Laptop
SDM845	—	`sdm845.c`	Flagship phone
SM8250	—	`sm8250.c`	Flagship phone
X1E80100	—	`x1e80100.c`	Premium laptop

File layout

QAudioAgent/
├── CLAUDE.md                          Runtime rules for Claude Code
├── AUDIO_CONTEXT.md                   Hardware reference (codecs, LPASS, ADSP, DT bindings)
├── .mcp.json                          MCP server configuration
├── .claude/
│   ├── settings.json                  Permissions (Bash(*) — full access)
│   ├── agents/                        10 domain subagents
│   │   ├── audio-core.md              ASoC machine driver
│   │   ├── audio-codec.md             WCD/WSA codec drivers
│   │   ├── audio-adsp.md              APR/GPR, AFE/ASM/ADM/PRM
│   │   ├── audio-reach.md             AudioReach/SPF graph
│   │   ├── audio-topology.md          DAPM widgets/routes
│   │   ├── audio-kernel.md            LPASS DMA/clocks/SoundWire
│   │   ├── audio-hal.md               Audio HAL / TinyALSA
│   │   ├── audio-calibration.md       ACDB / CVD / smart amp
│   │   ├── audio-knowledge.md         Knowledge boundary executor
│   │   └── audio-explore.md           Read-only exploration entry point
│   └── skills/                        13 skills
│       ├── qaudio-feature-orchestrator/
│       ├── qaudio-clarify/
│       ├── qaudio-research/
│       ├── qaudio-plan/
│       ├── qaudio-execute/
│       ├── qaudio-review/
│       ├── qaudio-validate/
│       ├── qaudio-debug/
│       ├── qaudio-build/
│       ├── qaudio-index/
│       ├── qaudio-knowledge/
│       ├── qaudio-cr-query/
│       ├── qaudio-design-doc/
│       │   └── scripts/generate_report.py
│       └── qaudio-reset-run/
├── knowledge/
│   ├── CONTRACT.md                    Knowledge boundary rules
│   └── wiki/                          11 seeded wiki pages
│       ├── INDEX.md
│       ├── architecture/              Platform pages (QCS9100, QCM6490, LPASS)
│       ├── hw/                        Codec families, SoundWire, APR/GPR
│       ├── layers/                    ADSP services, AudioReach, LPASS macros
│       └── debug/                     Failure patterns and log triage
├── scripts/
│   └── workspace_config.py            Read/write .qaudioagent/config.json
└── docs/
    └── run_report.html                Generated after each run (not committed)

Run artifacts

All generated during a run — deleted by /qaudio-reset-run:

.qaudioagent/
├── config.json            noble_root path — NOT deleted on reset
├── phase_outputs/
│   ├── clarify.json
│   ├── research.json
│   ├── plan.json
│   ├── execute.json
│   ├── review.json
│   └── validate.json
└── contracts/
    └── audio_core.json    (one per layer executed)

docs/run_report.html is also deleted on reset. Save it before running /qaudio-reset-run if you want to keep a record.

Exit and cleanup

To exit Claude Code:

/exit

or Ctrl+C.

Noble tree changes are not auto-committed. After a successful run, changes sit in the noble working tree as unstaged modifications. Your options:

# Keep and commit
git -C /path/to/noble add sound/soc/qcom/qcs9100.c sound/soc/qcom/sc8280xp.c
git -C /path/to/noble commit -m "ASoC: qcom: your message"

# Stash for later
git -C /path/to/noble stash push -m "qaudioagent: feature-name"

# Discard
git -C /path/to/noble checkout -- sound/soc/qcom/qcs9100.c sound/soc/qcom/sc8280xp.c

Navigation Menu

Repository files navigation

QAudioAgent

What it does

Quick start

1. Install Claude Code

2. Clone this agent

3. Launch Claude Code inside the agent directory

4. Run a feature

First-run walkthrough

Sample run

What works out of the box vs what needs setup

Setting up optional MCPs

All skills

Supported platforms

File layout

Run artifacts

Exit and cleanup

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
.qaudioagent		.qaudioagent
knowledge		knowledge
scripts		scripts
.mcp.json		.mcp.json
AUDIO_CONTEXT.md		AUDIO_CONTEXT.md
CLAUDE.md		CLAUDE.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

QAudioAgent

What it does

Quick start

1. Install Claude Code

2. Clone this agent

3. Launch Claude Code inside the agent directory

4. Run a feature

First-run walkthrough

Sample run

What works out of the box vs what needs setup

Setting up optional MCPs

All skills

Supported platforms

File layout

Run artifacts

Exit and cleanup

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages