FretAgent

An AI-powered guitar practice coach that generates personalised, research-backed practice plans. Describe your goal and skill level, and FretAgent builds a focused plan using live web research, music theory data, and peer-reviewed practice methodology.

How it works

The frontend sends your goal and difficulty level to an Express backend, which runs a Subconscious agentic reasoning loop (tim-claude engine). The agent has access to four tools:

Tool	Type	Description
web_search	Platform	Finds relevant tutorials, techniques, and song references
page_reader	Platform	Reads specific pages from search results in full
music_theory_lookup	Function (local)	Returns scale notes, chord progressions, and fretboard positions
research_paper_lookup	Function (local)	Searches curated excerpts from practice methodology research

Results stream back to the frontend as SSE events, rendering the plan in real-time with a live reasoning trace panel.

Tech stack

• Client — React 19 + TypeScript + Vite + Tailwind CSS
• Server — Node.js + Express 5 + TypeScript (tsx for dev)
• AI — Subconscious SDK (tim-claude engine)
• Tests — Vitest + Supertest

Project structure

FretAgent/
├── client/          # React frontend
│   └── src/
│       ├── components/   # UI components (ReasoningTrace, PracticePanel, etc.)
│       └── lib/          # API/SSE client logic
└── server/          # Express backend
    └── src/
        ├── routes/       # POST /api/agent — SSE streaming route
        ├── tools/        # music_theory_lookup and research_paper_lookup endpoints
        ├── data/         # papers.json — curated research paper excerpts
        └── app.ts        # Express app factory

Setup

Prerequisites

• Node.js 18+
• A Subconscious API key
• ngrok (free account) — required so Subconscious can call the local tool endpoints

1. Environment

cp .env.example .env

Fill in .env:

SUBCONSCIOUS_API_KEY=your_key_here
PORT=3001
TOOL_BASE_URL=https://your-ngrok-subdomain.ngrok-free.app

TOOL_BASE_URL must be the public ngrok URL pointing at the server. The Subconscious agent calls music_theory_lookup and research_paper_lookup over HTTP, so they must be publicly reachable.

2. Install dependencies

cd server && npm install
cd ../client && npm install

3. Start ngrok

ngrok http 3001

Copy the forwarding URL into TOOL_BASE_URL in .env. If you use a static ngrok domain (free tier), this URL never changes between restarts.

4. Start the server

cd server && npm run dev

5. Start the client

cd client && npm run dev

Open http://localhost:5173.

Running tests

cd server && npm test

Difficulty levels

Level	Description
Beginner	Open chords, easy keys, short sessions, no jargon
Intermediate	Technique refinement, music theory depth, more challenging repertoire
Advanced	Deep theory, advanced techniques, specific licks, professional methodology