It is not trying to solve music generation all at once. It is trying to make the loop inspectable.

Why symbolic MIDI

Audio generation is expensive and hard to inspect. MIDI is smaller, structured, and easier to evaluate. For early experiments, that matters.

The project starts with controls such as:

• mood
• energy
• density
• brightness

Those controls are simple, but they are useful enough to test whether the model responds to conditioning at all.

Training path

The first phase can generate toy piano MIDI without external datasets. It then tokenizes MIDI events, trains with MLX on Apple Silicon, and writes checkpoints plus training logs.

The repo also includes a MAESTRO import path. Since MAESTRO does not have mood labels, the importer creates heuristic weak labels from features such as tempo, density, velocity, silence, repetition, and pitch range.

That is the right level of honesty for the project: the labels are weak labels, not ground truth.

Generation and preview

Generated tokens can be exported back to MIDI. The project also has a local UI server that can generate and download MIDI files, with an optional audio-rendering path using FluidSynth and a local SoundFont.

This makes the experiment audible without turning it into a full production app.

What I learned

For music ML projects, the training loop is only one part of the system. The useful loop includes:

• dataset construction
• tokenization
• checkpointing
• generation controls
• structural evaluation
• audible preview

If any part is missing, it becomes hard to tell whether the model is improving or just producing plausible-looking tokens.

Current status

mood-midi-mlx is private and experimental. It is a research workbench for Apple Silicon rather than a finished listening product. That separation is useful: mood-midi-mlx can explore models, while driftloop can focus on a coherent listening experience.

That referee boundary is the most important design choice. The game engine holds the authoritative state and decides what each seat is allowed to see. The AI players only receive projected views.

Why the browser is the referee

Werewolf is an information game. The system must know the full state, but each player must see only a slice of it. If the AI seat receives hidden information by accident, the whole experiment is meaningless.

Nightfall keeps that boundary explicit:

• engine/ owns state, phase transitions, view projection, resolution, victory checks, and deterministic replay
• orchestrator/ runs the environment-independent game loop
• agentd-client/ calls POST /v1/turns
• app/ renders the spectator UI without owning game rules

The same engine can drive a Node CLI transcript or the browser spectator.

agentd integration

Nightfall does not embed agent logic. It calls an external agentd runtime. The werewolf, seer, and villager agents live on the agentd side as personas and model choices. Nightfall only maps roles to agent_ref values and sends the projected view for the current seat and phase.

That separation matters. The game should own rules; agentd should own agent execution.

Game shape

The current board is intentionally small:

• 6 seats
• 2 wolves
• 1 seer
• 3 villagers
• no role reveal on death
• loop: night seer, night wolf, day discussion, day vote

Victory is checked after deaths: wolves eliminated means good wins; all villagers dead means wolves win. Killing the seer does not end the game, it only removes the good side’s information source.

What I learned

Games are useful agent testbeds because they force state discipline. A chat bot can hide vague behavior behind language. A game cannot. The engine needs phases, legal actions, projected views, victory rules, and reproducible transcripts.

Nightfall is also a reminder that a good agent integration is often just a clean boundary. The AI seat should not know the whole game. It should know what that player would know.

Current status

Nightfall is private and experimental. It is useful as an AI interaction lab, especially for testing information hiding, role-specific personas, and multi-agent turn orchestration.

The useful distinction is that Canopy does not try to be a map app. It is a route-planning capability.

Why this exists

Singapore cycling routes are not only about shortest path. A good route often means:

• prefer PCN-like paths
• avoid high-car roads
• keep loops close to a target distance
• export a track that can be followed elsewhere
• explain how much of the route is car-free or on-road

General routing APIs are not always good at expressing those preferences. Canopy uses a self-hosted GraphHopper service with a custom bike profile that strongly prefers cycleways, PCN-like paths, and low-car links while penalizing motor roads.

OneMap is used for geocoding and POIs, not routing.

Tool surface

The MCP server exposes tools such as:

• geocode(query)
• plan_loop(start, distance_km, direction?, prefer="pcn")
• route(origin, destination, prefer="pcn")
• pois_along(geometry, types=[...])
• audit_route(geometry)
• export_gpx(geometry, name)

That gives an agent a clean workflow: resolve a place, plan a route, audit the result, find POIs along the corridor, and export GPX.

Honest boundaries

Canopy optimizes for low-car and away-from-traffic routing. It does not avoid pedestrians, because Singapore PCNs are shared paths.

Round-trip distance is also approximate in GraphHopper. Canopy tries multiple seeds and scaled requests, then returns the actual distance instead of pretending the target was exact.

The project also intentionally avoids building turn-by-turn navigation. A downstream app can load the generated GPX track into something like OsmAnd or CoMaps.

What I learned

MCP is a good fit when the tool is specific and verifiable. Route planning should not be hidden inside a chat answer. The agent should call a tool that returns geometry, distance, audit percentages, and a GPX path.

For location work, the agent’s job is orchestration. The route engine should still be a route engine.

Current status

Canopy is private and active. It is tied to local Singapore routing data, OneMap credentials, and a local GraphHopper runtime, so the repo is not a clean general-purpose hosted service.

The interesting constraint is that it aims to use open data and avoid API keys where possible.

Why maps are hard for language models

Map questions sound simple:

• find coffee near me
• show quiet parks nearby
• route to a place with shade
• find restaurants within walking distance

But those questions mix language, location, distance, categories, freshness, and user context. A language model can understand the request, but it should not invent geography.

The system needs tools.

Open-data shape

The project uses sources such as OpenStreetMap, Nominatim, Overpass, Wikimedia REST, and related open endpoints. The map UI is built around Leaflet and React.

The model’s role is to translate intent into geospatial operations:

• what is the user looking for?
• what radius or location matters?
• is this a route, POI search, or environment query?
• what enrichment should be added?

The tools then fetch actual data.

Product boundary

The app should be honest about uncertainty. Open geospatial data is uneven. Names change, POI tags are inconsistent, and “quiet” or “hipster” are semantic hints rather than guaranteed database fields.

That means the UI should show results as interpreted matches, not absolute truth.

What I learned

Natural-language interfaces work best when they produce inspectable structured plans. If the app can show the interpreted action, it becomes much easier to debug:

• searched category
• center point
• radius
• data source
• filters
• enrichment steps

This is especially important for maps because wrong answers can look visually convincing.

Current status

map-ask is private and prototype-stage. It is safe to discuss as an architecture pattern: use an LLM for intent shaping, then rely on real geospatial tools for facts.

The project exists because raw prompting is not enough for repeated technical work.

What is inside

The repo contains skills such as:

• OceanBase solution architect guidance
• OceanBase DDL syntax checking
• seekdb-backed DDL validation

Each skill tries to narrow the agent’s behavior for a specific kind of work. Instead of asking a general model to “help with OceanBase,” the skill defines what kind of answer is expected, which constraints matter, and which validation path should be used.

Why skills instead of notes

Traditional notes help humans. Skills help agents act more consistently.

That difference matters. A good skill should:

• define the task boundary
• mention common failure modes
• route to validation where possible
• make assumptions explicit
• avoid generic advice when concrete checks exist

For database work, this is especially useful because the cost of vague answers is high. A DDL suggestion that sounds plausible but violates grammar or deployment constraints is worse than no suggestion.

The useful pattern

The best skills are not huge knowledge dumps. They are small operational wrappers around repeatable judgment.

For example, a DDL validation skill should not merely explain DDL. It should push the agent toward an actual validation path and make clear when offline validation is possible.

That is the difference between “LLM as autocomplete” and “LLM as a guided operator.”

What I learned

Agent quality improves when domain knowledge is packaged close to the workflow. It is not enough to rely on the model remembering a product correctly.

Skills are also easier to maintain than long prompts embedded in many tools. If a rule changes, update the skill. If a validation command improves, update the skill. The agent workflows that use it inherit the better behavior.

Open source status

ob-skills is public because the project is mostly guidance and validation workflow. It is a good fit for sharing: others can inspect the assumptions, reuse the structure, or adapt the skill pattern to their own database work.

That is a different direction from the first version of this note, which described agentd mainly as a Wasm-native harness. The pushed version is now more concrete: an Agent is a manifest with a system prompt, visible tool catalog, resource limits, and a model choice. The actual handler is the built-in generic agent.

Turn API

A caller submits:

POST /v1/turns

with a tenant, agent_ref, scope, and payload. The runtime creates an AgentRun, resolves a lane, assembles the visible tools, invokes the generic agent, and records a structured final_decision.

There is no push side. A Telegram bot, a browser game, or another transport bridge should call the API and render the result itself. That keeps agentd from becoming coupled to a specific messaging system.

Capability surface

The current public tool surface includes:

• plan.*
• run.*
• schedule.*
• artifact.*
• memory.*
• context.*
• web.*
• clock.*
• llm.*
• output.*

The important pattern is that tools carry reliability metadata: maturity, idempotency, side-effect scope, failure classes, replay expectations, and delivery semantics. That metadata is part of making agent behavior inspectable instead of magical.

Storage model

Durable state now lives in SeekDB, a MySQL-compatible OceanBase-derived database. Control-plane state, context, artifacts, and memory all use that one database boundary. Memory is per tenant and uses native vector plus full-text retrieval.

This is a pragmatic simplification. There is no MinIO, S3, Litestream, or separate object store in the core path.

What I learned

Agents need less magic and more runtime discipline. Even a personal agent runtime has to answer boring operational questions:

• context scopes matter
• retries can duplicate work
• memory needs indexing and pruning
• tools need permission boundaries
• failures need artifacts and logs
• callers need a stable way to wait for output

The useful boundary is no longer just Wasm. It is the turn contract plus explicit host capabilities.

Current status

agentd is experimental and private. It is useful as a lab for runtime shape, but I do not consider it a public platform yet. The public lesson is the architecture: keep transports outside the core runtime, keep tool capabilities explicit, and make every run produce inspectable output.

The idea is simple: keep local inference usable by normal OpenAI SDK clients.

Why this exists

Local models are most useful when they can plug into existing tools. A model that only works through a special command is interesting, but a model that looks like an OpenAI-compatible service can be used by editors, agents, scripts, and gateways.

That is the purpose of qwen-local. It is not a model research project. It is an adapter and runtime boundary.

The default shape is:

• MLX for Apple Silicon inference
• Qwen for chat
• Qwen embeddings
• Qwen3 TTS through mlx-audio
• MLX Whisper for speech-to-text
• one /v1 API surface

Once models are cached, inference should not require external API calls.

The useful constraint: 16 GB

The project targets a realistic personal machine rather than a workstation with huge memory. That constraint forces decisions:

• prefer quantized models
• keep concurrency conservative
• avoid loading every capability eagerly if it hurts responsiveness
• make stuck inference and runtime locks visible

Local AI services fail in different ways from hosted APIs. A hosted provider returns rate-limit errors or provider errors. A local process can get memory pressure, model load stalls, file cache problems, or long single-user queues.

That makes operational behavior part of the product.

Relationship to tailgate

qwen-local is the local model service. Tailgate is the gateway that decides when to use it.

Keeping those roles separate matters. The local service should focus on model loading, request compatibility, and media endpoints. The gateway can handle policy, provider selection, fallback, and external clients.

That split keeps qwen-local from becoming a general AI router.

What I learned

OpenAI-compatible does not mean full OpenAI clone. The useful target is compatibility for the clients I actually use:

• chat completions
• embeddings
• speech generation
• transcription
• predictable model IDs
• normal error shapes where possible

The second lesson is that local inference needs a health model. It is not enough to expose an endpoint. I need to know whether the service is loaded, busy, stuck, or unavailable, especially when another tool is routing requests into it.

June 2026 update

The pushed version has moved the local speech stack from Kokoro to Qwen3 TTS. The default TTS model is now mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit, served through mlx-audio with local-tts as the API model alias. The default voice is vivian, and "default" maps to that voice.

This keeps the project aligned around Qwen for chat, embeddings, and speech while still keeping Whisper as the ASR backend. It also reinforces the single-worker assumption: chat, embeddings, TTS, and ASR all share one serialized local inference worker so the Mac does not get overloaded by parallel requests.

Open source status

This project is private because it includes local operational assumptions and is tuned for my own machine. The general pattern is public enough to discuss: make local models boring by putting them behind familiar API contracts.

It is not meant to be a public model marketplace. The point is not to replace OpenRouter or any other provider. The point is to make my own AI workflow less scattered.

The problem

Once you use multiple model providers, the configuration spreads quickly:

• local model endpoint
• hosted model provider keys
• fallback behavior
• model names
• pricing assumptions
• tool-specific environment variables
• different capabilities for chat, embeddings, speech, and transcription

Every client wants a slightly different setup. That is annoying for normal use and worse for agents, because agent configuration should be boring and repeatable.

Tailgate puts that complexity behind one OpenAI-compatible surface.

Design shape

The core API follows familiar endpoints:

• GET /v1/models
• POST /v1/chat/completions
• POST /v1/embeddings
• POST /v1/audio/speech
• POST /v1/audio/transcriptions

Behind that surface, the gateway can route requests to local qwen-local, DeepSeek, OpenRouter, or future compatible providers. It tracks provider health, supports streaming passthrough, and can apply simple route selection rules.

The most useful rule is not fancy AI logic. It is policy:

• prefer local when the task fits
• keep secrets off client machines
• avoid sending private work to external providers accidentally
• fall back only when the route explicitly allows it

Why private

Tailgate contains too many assumptions about my own environment to be a clean open source project. It is shaped around private networking, provider credentials, model preferences, and operational defaults.

The public lesson is still useful: an AI gateway does not need to start as a large platform. For one person, it can simply be a policy boundary.

What I learned

The biggest value of a gateway is not only key management. It is reducing mental overhead.

Before the gateway, every tool needed to know too much. After the gateway, tools only need:

• one base URL
• one API key or private network policy
• normal OpenAI-compatible request shapes

That makes experiments cheaper. I can change the provider map without editing every client.

The second lesson is that local models need protection. A small local model service may only handle one heavy inference at a time. A gateway can enforce concurrency and fallback rules so clients do not accidentally overload the local runtime.

June 2026 update

The pushed version has a clearer premium route. premium/chat now prefers the configured DeepSeek premium model before falling back to the configured OpenRouter premium model. Config order is also used as a tiebreaker when candidates have the same price ranking, which keeps routing behavior predictable instead of surprising.

This is a good example of the gateway’s real job: not to be clever, but to make model policy explicit. A client can ask for premium/chat; Tailgate decides which concrete upstream model should satisfy that tier.

Current status

Tailgate is active and private. I expect it to stay private unless the configuration model becomes generic enough to be useful outside my own setup.

The important constraint is that there is no backend inference service. The browser is not just the UI; it is also the runtime.

Why build it

Most translation tools are service-shaped: text goes to a server, the server runs a model, and the result comes back. That is fine for many cases, but it is also more infrastructure than I wanted for a narrow personal tool.

PocketBabel asks a smaller question: if the scope is only English to Chinese and Chinese to English, can the whole product be a static site?

That decision makes the system easier to reason about:

• no API key
• no account system
• no backend deployment
• no request logging
• no server-side scaling problem

The cost is that the first model download matters and browser performance becomes part of the product.

Product boundary

The project intentionally avoids becoming a general translation platform. The current shape is narrow:

• English to Chinese
• Chinese to English
• text input and output
• desktop and mobile browser support
• PWA shell and offline reuse

It does not try to support OCR, speech input, synced history, arbitrary language pairs, or collaborative workflows. Those features are tempting, but they would change the project from a useful small app into a maintenance surface.

Technical shape

The implementation is a React and Vite app. Translation is handled by transformers.js with browser-side model loading and caching. Deployment is static, which makes Cloudflare Pages a natural fit.

The UI challenge is not only making a textarea and a button. The app needs to explain model state without becoming noisy:

• model not downloaded yet
• model loading
• translation running
• offline reuse available
• failure state when the browser cannot support the runtime well

For an app like this, good status text is part of the architecture. If users do not know whether the model is downloading, warming up, or stuck, the app feels broken even when the code is doing the right thing.

What I learned

Browser AI is practical when the product scope is narrow. It is much less practical when you pretend the browser is a free replacement for a server.

The useful pattern is:

1. choose a task with a clear input and output
2. constrain the model set
3. make loading and caching behavior visible
4. avoid account and sync features unless they are essential

PocketBabel works because it does not try to be Google Translate. It is a small translation surface for a small set of language directions.

June 2026 update

The pushed version has grown in two small but useful directions without changing the core product boundary.

First, short word or phrase inputs can now use dictionary-style prompts. That makes PocketBabel more useful for vocabulary lookup: instead of treating every short input as a sentence, the app can ask for meanings, part-of-speech style structure, and usage notes.

Second, translated output can be read aloud through the browser’s speechSynthesis API when the browser supports it. This is deliberately output speech, not speech input or speech translation. It keeps the app frontend-only while making the translated result easier to check.

Open source status

PocketBabel is public because the architecture is self-contained and does not rely on private infrastructure. It is also a good example of the kind of project that benefits from being inspectable: the privacy story is stronger when the code path is visible.

This post is intentionally sanitized. I am not including tokens, local machine details, private paths, secrets, or any internal repository configuration that should not be published.

Official Symphony resources

If you are trying to reproduce or extend this setup, start from the upstream project rather than this blog post alone:

• Repository: github.com/openai/symphony — source, issues, and release notes.
• Specification: SPEC.md — describes the intended behavior and interfaces.
• Reference implementation: elixir/ — Elixir-based reference; follow the README there for build and run details.

Symphony is positioned as experimental or preview-quality software; run it only in environments and repositories you trust, and read the repo README for current limitations and safety expectations.

Hands-on: from clone to first run

Everything below follows the Elixir reference README. If a step fails, fix that step before tweaking your narrative expectations—the runtime is strict about valid WORKFLOW.md YAML at startup.

0. Prerequisites

• Linear: a workspace where you can create a project and issues inside that project.

• Linear API key: Settings → Security & access → Personal API keys. Export it in your shell (do not commit it):

  export LINEAR_API_KEY="your_linear_personal_api_key"
  

• Codex CLI with codex app-server available (Symphony launches Codex in App Server mode). Ensure codex is on PATH when the codex.command in WORKFLOW.md runs.

• Runtime for the reference implementation: the upstream docs recommend mise for Erlang/Elixir versions; use mise install in symphony/elixir as documented.

1. Linear setup: workspace, team, project, workflow, and API key

Symphony only sees what Linear exposes through the API. If the board is wrong, every later step looks like a Symphony bug. Configure Linear before you wire project_slug into WORKFLOW.md.

1.1 Workspace and team

• Use a Linear workspace you control (personal or org). You need permission to create projects and issues on a team.
• Pick the team that will own the automated work. Issues are always tied to a team; your project will live under that team’s context. For a solo setup, one dedicated team per “product line” or per repo is enough.

1.2 Create a project (this is the Symphony queue boundary)

1. In Linear, open Projects (or the team’s project list) and create a new project for the repository you are automating (for example one GitHub repo ↔ one Linear project).
2. Give it a clear name so you do not file issues into the wrong queue later.
3. Open the project itself—not only the team backlog. Symphony’s tracker.project_slug refers to this project.

1.3 Read the project_slug correctly

1. With the project open, copy the page URL from the browser address bar (or use “Copy link” if Linear offers it for the project).
2. The slug is the identifier in that URL that points at this project. Paste it into WORKFLOW.md as project_slug exactly—same spelling, same segment the URL uses.
3. If you rename the project or move it, re-check the URL and update WORKFLOW.md; a stale slug is an instant “nothing happens” failure.

1.4 Align workflow states with WORKFLOW.md

Your simplified WORKFLOW.md lists active_states and terminal_states (for example Todo, In Progress, Rework, Merging, and terminals like Done, Canceled, Cancelled, Duplicate).

1. In Linear, open Team settings → Workflow (wording may vary slightly by plan and UI version).
2. Ensure the team that owns this project actually has status names that match what you put in YAML—including spelling (Canceled vs Cancelled are different strings).
3. If a state is missing, add it to the team workflow. If Linear ships a default you do not use (for example an extra backlog column), you can leave it unused; what matters is that every state your agent and YAML mention exists on the board.
4. Decide how issues enter the pipeline: many setups use Todo or In Progress as the first “Symphony should care” state. Put that state in active_states so polling can pick the issue up.

1.5 Personal API key (Symphony uses LINEAR_API_KEY)

1. Open your user Settings → Security & access (or API / Personal API keys, depending on Linear’s UI).
2. Create a new personal API key, give it a label you will recognize (for example symphony-local).
3. Copy the key once, set export LINEAR_API_KEY="..." on the machine that runs Symphony, and never commit it to git or paste it into WORKFLOW.md unless you intentionally use env indirection like tracker.api_key: $LINEAR_API_KEY (still keep secrets out of the repo).

1.6 Creating issues the way Symphony expects

1. Create the issue inside the project: from the project view, use New issue (or equivalent) so the issue is associated with that project. Creating an issue only on the team backlog without attaching the project is the classic “Symphony is idle” mistake.
2. Set title and description to something actionable; the Markdown body of WORKFLOW.md passes issue.title and issue.description into Codex.
3. Move the issue to a state listed under active_states (for example Todo or In Progress) so it is not sitting in a column Symphony does not poll.

1.7 Optional but useful

• Templates: a small issue template (context, acceptance criteria, “how to validate”) makes agent runs less ambiguous.
• Labels: optional; Symphony does not require them unless you add logic elsewhere.
• Permissions: if the API key belongs to a restricted user, confirm that user can read and update issues in the target project.

After this, you can copy project_slug into WORKFLOW.md with confidence. If anything in this section is skipped, revisit 1.3 (slug) and 1.6 (issue in project) first when debugging.

2. Build the Symphony binary (reference implementation)

git clone https://github.com/openai/symphony
cd symphony/elixir
mise trust
mise install
mise exec -- mix setup
mise exec -- mix build

After this, the launcher is ./bin/symphony inside symphony/elixir (see the same README). You can start it with an absolute path to any WORKFLOW.md you maintain:

mise exec -- ./bin/symphony /absolute/path/to/your/repo/WORKFLOW.md

If you omit the path, it defaults to ./WORKFLOW.md in the current directory—useful when you are iterating inside a single checkout.

Optional flags from upstream:

• --logs-root — log directory (default: ./log relative to how you invoke the binary).
• --port — also starts the optional Phoenix observability UI (dashboard/API as described in the Elixir README).

3. Add WORKFLOW.md to the repository you want automated

1. Copy the template from the Symphony repo: elixir/WORKFLOW.md → your target repo (often repo root).

2. Edit the YAML front matter for your world:

   • tracker.project_slug: in Linear, open your project, copy its URL from the browser, and take the slug segment (the README describes this explicitly).
   • workspace.root: a directory on disk where Symphony may create one workspace per issue (large disk is fine; this is not your git clone root—it is a parent for per-issue workspaces).
   • hooks.after_create: typically git clone ... . into that workspace so Codex works on a fresh copy of your code. Use the clone URL and branch you actually use (HTTPS or SSH is your choice; private repos need credentials on the machine running Symphony).
   • codex.command: must match how you invoke App Server locally (model flags, config, etc.). If this command is wrong, the agent never comes up cleanly.

3. Align Linear workflow states with what WORKFLOW.md expects. The stock template references states such as Todo, In Progress, Rework, Human Review, and Merging. If your team uses different names, either rename states in Linear (Team Settings → Workflow) or edit active_states / terminal_states and the Markdown “status map” in WORKFLOW.md so they match reality.

4. Optionally copy the skills from the Symphony repo (commit, push, pull, land, linear, etc.) into your repo if your workflow prompt expects them—the Elixir README calls this out.

Symphony does not boot if WORKFLOW.md is missing or the YAML front matter is invalid; fix the file and restart.

4. Run and sanity-check before opening a ticket

export LINEAR_API_KEY="..."   # if not already in your shell profile
cd /path/to/openai/symphony/elixir
mise exec -- ./bin/symphony /path/to/your/automated/repo/WORKFLOW.md

Then verify:

• The process stays running and polls on the interval you set (polling.interval_ms in the template).
• If you passed --port, you can hit the dashboard/API URLs documented in the Elixir README for live state.

5. First Linear issue (the mistake that looks like “Symphony is broken”)

Do this in order or you will get silent no-ops:

1. Create or pick a Linear project whose slug matches tracker.project_slug exactly.
2. Create the issue inside that project, not as a free-floating team issue.
3. Put the issue in an active state listed under active_states in WORKFLOW.md (for the default template, something like Todo or In Progress—not Backlog if your prompt tells the agent to ignore Backlog).

If Symphony polls successfully but your issue never enters the watched project, you will see healthy logs and zero useful work—this is the project_slug lesson from later in this post.

6. Two repos (repeat the pattern)

For each codebase, maintain its own WORKFLOW.md, its own Linear project (and slug), its own workspace.root, and run its own ./bin/symphony .../WORKFLOW.md process. Trying to multiplex multiple repositories through one workflow file is how you get accidental coupling and confusing failures.

If you want the upstream one-liner to bootstrap with Codex inside your repo, the FAQ in the Elixir README suggests pointing Codex at elixir/README.md and asking it to wire files for your codebase—still verify project_slug, workspace paths, and git remotes yourself.

Why I tried this

What interested me most about Symphony was not “AI that writes code” in isolation. I already have coding tools for that. The interesting part was orchestration:

• a task source
• a state machine
• an isolated workspace per task
• an agent runtime
• a repeatable loop from issue to code change

That is a different shape of workflow from normal editor-assisted coding.

Why I used Linear instead of GitHub Issues

One thing became clear very quickly: Symphony is designed around Linear as the source of truth for work. It does not naturally start from GitHub Issues. Instead, the workflow looks more like this:

1. Create a Linear issue
2. Symphony polls the configured Linear project
3. Symphony creates a dedicated workspace for that issue
4. Codex works inside that workspace
5. The workflow advances by issue state

At first this felt a little strange, because I am used to GitHub Issues being the center of project work. But after testing it, I could see the logic. Linear is the task system. GitHub is the code system.

The first practical lesson: project scoping matters

A surprisingly easy mistake was creating an issue in the wrong place.

I had a Linear workspace and a correctly configured project, but the first issue I created was not actually attached to the project that Symphony was watching. From the outside it looked like “nothing is happening,” but the real problem was much simpler: Symphony was correctly polling the configured project and my issue was outside that scope.

That was a good reminder that in this setup, project_slug is not a decorative field. It is the queue boundary.

Making WORKFLOW.md actually usable

The stock elixir/WORKFLOW.md in the Symphony repository is intentionally large: long status maps, PR sweeps, workpad templates, and guardrails meant for serious team-style orchestration. For solo maintenance on a small repo, that is often more surface area than you want to own on day one.

What I actually wanted was a small YAML front matter plus a short agent brief that still respects Linear state and runs a tight validate loop.

The elements I kept in practice:

• one Linear project per repository
• one Symphony process per repository
• one workspace root per repository
• explicit active and terminal states (only the ones I really use)
• explicit install/setup commands in after_create
• explicit validation before completion (npm in my case)
• codex app-server with sandbox left at workspace write, approval policy set explicitly so the run does not stall on prompts

A simplified WORKFLOW.md (sanitized)

Below is the shape of the workflow file I run. Values such as the Linear project slug, workspace directory, and git remote are placeholders—replace them with your own. Do not copy real identifiers from this post into production without checking them in Linear and Git.

---
tracker:
  kind: linear
  project_slug: "your-linear-project-slug"
  active_states:
    - Todo
    - In Progress
    - Rework
    - Merging
  terminal_states:
    - Done
    - Canceled
    - Cancelled
    - Duplicate

polling:
  interval_ms: 5000

workspace:
  root: ~/symphony-workspaces/your-repo-short-name

hooks:
  after_create: |
    git clone --depth 1 https://github.com/your-org/your-repo.git .
    npm install

agent:
  max_concurrent_agents: 1
  max_turns: 20

codex:
  command: codex app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite
---

You are working on a Linear issue {{ issue.identifier }}.

Title: {{ issue.title }}
Body: {{ issue.description }}

Rules:

- Always start by understanding the current state of the issue.
- If state is Todo, move it to In Progress.
- If state is Rework, review existing changes and fix issues.
- If state is Merging, finalize merge (do not keep coding).

Execution:

1. Understand the task
2. Reproduce or reason about current behavior
3. Make minimal safe changes
4. Run:
   - npm run build OR npm test
5. If success:
   - commit changes
   - push branch or merge directly according to repository flow

Do not:

- Ask humans for help
- Modify files outside workspace
- Skip validation

Goal:

Deliver working code change with valid validation and keep the Linear issue state accurate.

How to fill this in safely

• project_slug: in Linear, open the project and copy its URL; the slug is the path segment that identifies the project (see the Elixir README). It must match the project where you create issues.
• workspace.root: any empty-friendly parent directory on the machine that runs Symphony; Symphony creates a subdirectory per issue under this root.
• after_create: use your real git clone URL and package install command (npm install, pnpm install, make, and so on).
• Linear states: your team must actually define or use states compatible with active_states / terminal_states. If Linear uses different names, edit the lists to match.

This was a much better balance for me than copying the entire official workflow verbatim, while still staying inside Symphony’s YAML + Markdown contract.

The first real run

Once the workflow was wired correctly, the first successful run was a great moment. The basic flow worked:

1. Create a Linear issue
2. Symphony picks it up
3. A workspace is created
4. The repository is cloned
5. Dependencies are installed
6. Codex makes a change
7. Validation runs
8. The issue moves forward in the workflow

That first time matters because it changes the whole thing from “interesting repo I am reading” into “real tool I can use.”

A workflow surprise: no PR, direct merge

One unexpected result was that the run did not produce a pull request. Instead, it created a branch and then merged directly into main.

For a team workflow, that would be a problem. For my personal setup, I actually found it acceptable.

Because I am the only person using this flow right now, direct merge is not automatically bad. It is fast, and it fits a solo maintenance loop. The tradeoff is obvious: less review structure, more need for good validation and discipline.

If I later want a stricter process, the right fix is probably branch protection plus a stronger PR gate in the workflow.

Why I accepted a “solo mode”

After thinking about it, I realized there are really two different modes here:

Team mode

• branch protection
• pull requests
• human review gates
• merge discipline

Solo mode

• fast issue pickup
• direct code change
• direct landing when validation passes

For now I am explicitly leaning toward solo mode. That is not because it is universally better. It is just a better fit for a single developer trying to reduce friction on personal repos.

Scaling from one repo to two

After getting the first repository working, I wanted to know whether I could use Symphony across more than one repo.

The answer was yes, but not by forcing one workflow to manage everything. The cleaner model was:

• one Linear project per repository
• one WORKFLOW file per repository
• one Symphony process per repository
• one workspace root per repository

That means each repo gets its own queue, workspace, and execution loop. The result is much easier to reason about than trying to multiplex multiple repos through a single workflow.

Conceptually, the setup became:

Repo A -> Linear Project A -> Symphony Process A
Repo B -> Linear Project B -> Symphony Process B

That separation made the system feel much more stable.

Things that felt weird

A few things still feel unusual in this setup:

1. Linear is the real driver

If you are used to GitHub-centric project flow, it takes a minute to reset your intuition.

2. The workflow file is closer to an operating manual than a config file

It is not just about parameters. It strongly shapes agent behavior.

3. Small scope mistakes create “silent failures”

If the wrong project is watched, or the issue is created in the wrong place, everything can look healthy while nothing useful happens.

4. Defaults are often too implicit

Model choice, reasoning depth, safety behavior, and merge style all become much clearer once they are explicitly set instead of left to defaults.

What I would improve next

There are a few upgrades that would make this setup stronger without making it too heavyweight:

• make validation stricter before landing changes
• make commit messages more informative
• optionally require PRs for selected repos
• capture a better audit trail of what the agent actually did
• design a lightweight rollback path for bad automated changes

That would preserve the speed of solo mode while reducing the risk of bad direct merges.

Final take

My main takeaway is that Symphony becomes much more interesting once it is treated as a workflow runtime, not just a coding demo.

The useful mental model is not “an AI that edits files.” It is closer to this:

• work arrives through a queue
• each task gets an isolated environment
• the agent runs inside a bounded workflow
• the repo is just one part of the system

For a solo developer, that can actually be a very comfortable way to work, as long as the workflow is shaped carefully enough.

It is still early, still a little rough, and definitely not something I would blindly trust everywhere. But for small personal projects, it already feels surprisingly real.

Future potential: kill the relay

Symphony is not competing with tab completion. It is a probe for a nastier question: if work is just queue + policy + execution, why would you keep a permanent class of people whose main job is to sit between a customer sentence and a git merge?

Here is the version I actually believe.

B2B should look like a pipe, not a committee. Whoever hears the customer—sales engineer, CS, onboarding, whoever—opens the issue. That issue is the contract. Behind it, Symphony-grade orchestration does the rest: clone, implement, test, merge, release. Not “faster Jira.” Not “AI assists your sprint.” The default path is machine throughput; humans are for edge cases, politics, and blame.

Does that erase humans? No—it erases the middle. The classic career ladder where “product” rewrites reality for “engineering” so engineering can rewrite it again for Git is not destiny. It is coordination rent. Orchestration is a wrecking ball aimed at that rent. If your value is mostly translating between tools and meetings, the stack is not coming to help you—it is coming to delete the slot.

You can list risks forever—compliance, security, hallucinations, bad merges—and you should. But risk is not a moral argument for headcount. It is an argument for thinner, sharper ownership: a tiny number of people who set policy and own catastrophes, plus a machine that does the boring middle at machine speed.

Yes, today’s tools are still a preview: flaky, embarrassing, unsafe if you are lazy about validation. Irrelevant to the direction. The direction is first-hand demand in, shipped software out, with as few interpreters as the market will tolerate. In ten years, “we need more PMs and more engineers because that is how software is made” will read like “we need more telephone switchboard operators because calls exist.”

My two-repo setup is a toy. The logic is not.

Appendix: sanitized lessons learned

• Configure Linear (project, slug, workflow states, API key, issues inside the project) before blaming Symphony
• Start with one repo, not many
• Keep one workflow per repo
• Use one Linear project per repo
• Make state transitions explicit
• Do not rely too much on defaults
• Validate aggressively before allowing automated landing
• Expect the first “nothing happened” failure to be a scoping mistake

We’ve all been there. You’re deep in a technical discussion with an AI assistant—analyzing code, exploring architecture, or debugging a complex issue. The conversation is rich with insights, and you think: “This would make a great blog post.”

But then reality hits: you need to switch to your blog repository, format the content, commit it, push it, and wait for the build. By the time you’re back, the original context is gone, and the momentum is lost.

What if you could publish directly from where you are?

Building on Existing Automation

In my previous post about automatically publishing a blog using GitHub Actions, I set up a workflow where pushing to the blog repository triggers an automatic build and deployment to GitHub Pages. This solved the build and deployment automation, but there was still one manual step remaining: creating the post file itself.

The workflow I described there handles:

1. Checking out the blog repository
2. Building the Hugo site with make
3. Deploying to jackysp.github.io

But you still needed to be in the blog repository to create the post. That’s where MCP changes everything.

Enter MCP: The Missing Link

The Model Context Protocol (MCP) is revolutionizing how AI agents interact with external systems. Instead of treating AI as a passive tool, MCP enables agents to act as autonomous agents with direct access to your tools and workflows.

In my setup, I’ve connected MCP-enabled agents (like Cursor) directly to my blog repository via GitHub MCP. This means:

• No context switching: Stay in your current working directory, whether it’s a random project folder or a deep codebase exploration
• Preserve conversation flow: The AI maintains the full context of your discussion
• Direct publishing: Create and publish posts without leaving your IDE

The Architecture: Seamless Integration

Here’s how the complete workflow operates:

┌─────────────────────────────────────────────────────────┐
│  AI Agent (Cursor/Claude) with MCP enabled              │
│  - Context: Any code repository or discussion            │
│  - Tool: GitHub MCP Server                               │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ Creates post via GitHub MCP
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  Blog Repository (jackysp/blog)                         │
│  - content/posts/<slug>/index.md                        │
│  - Commit: "Publish: [title]"                           │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ Push to master branch
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  GitHub Actions (from previous post)                     │
│  - Build: Hugo static site generation                   │
│  - Deploy: Push to jackysp.github.io                    │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ Published
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│  Live Site (jackysp.github.io)                          │
│  - Post is live and accessible                           │
└─────────────────────────────────────────────────────────┘

The GitHub Actions part remains exactly as described in the previous post—no changes needed there. The MCP layer adds the ability to trigger it from anywhere.

The Workflow in Action

1. AI-Powered Content Creation

When you’re discussing a technical topic with an AI agent, you can simply ask:

“Turn this discussion into a blog post and publish it.”

The AI agent, with access to GitHub via MCP, can:

• Extract key insights from your conversation
• Format content according to Hugo front matter requirements
• Create properly structured markdown files
• Handle images and assets
• Commit and push to the repository

2. Automated Build & Deploy

The moment a post is pushed to the master branch, the same GitHub Actions workflow from the previous post kicks in:

on:
  push:
    branches: [ master ]

The workflow (as detailed in the previous post):

1. Checks out the blog repository with submodules
2. Builds the Hugo site using make
3. Deploys the built artifacts to jackysp.github.io

All without manual intervention.

3. Governance Through Contracts

To ensure quality and prevent accidents, I’ve implemented an AI Publishing Contract (PUBLISHING.md) that defines:

• Allowed paths: Only content/** and static/** can be modified
• Post format: Required front matter fields (title, date, tags, slug, summary)
• Image handling: Standardized location and reference format
• Commit conventions: Single commit per post with descriptive messages

This contract ensures that AI agents can publish content while respecting the repository structure and quality standards.

Why This Matters: The Developer Experience Revolution

Zero Context Switching

Traditional workflow:

1. Copy conversation → Switch to blog repo → Format → Commit → Push → Wait
2. Context lost, momentum broken

New workflow:

1. Ask AI to publish → Done
2. Context preserved, workflow continuous

Capturing Technical Insights

The best technical insights often emerge during active problem-solving. With this workflow, you can:

• Document discoveries in real-time
• Turn debugging sessions into tutorials
• Transform architecture discussions into deep-dives
• Share codebase explorations as learning resources

Scaling Knowledge Sharing

Previously, the friction of publishing meant many valuable insights were never written down. Now, the barrier to publishing is minimal, making it easier to:

• Share learnings with your team
• Build a personal knowledge base
• Contribute to the developer community
• Document your problem-solving journey

Technical Implementation Details

MCP Server Configuration

The GitHub MCP server provides the AI agent with:

• Repository read/write access
• File creation and modification
• Commit and push capabilities
• Branch management

GitHub Actions Workflow

The CI/CD pipeline (as described in the previous post) handles:

• Go environment setup (for Hugo builds)
• Repository checkout with submodules
• Site generation via make
• Deployment to GitHub Pages repository

No changes needed to the existing workflow—it just gets triggered from a new entry point.

Hugo Site Configuration

Posts follow Hugo’s standard structure:

• Location: content/posts/<slug>/index.md
• Format: YAML front matter + Markdown content
• Images: Stored in each post bundle and referenced with relative filenames
• Draft control: draft: true/false for preview/publish

The Future: AI-Augmented Documentation

This workflow represents a shift toward AI-augmented documentation. Instead of treating AI as a writing assistant, we’re treating it as a publishing agent that can:

• Understand context from code discussions
• Extract technical insights automatically
• Format and structure content appropriately
• Publish without breaking workflow

As MCP and similar protocols mature, we’ll see more sophisticated capabilities:

• Automatic code analysis and explanation
• Multi-post series generation from extended discussions
• Cross-referencing with existing content
• SEO and metadata optimization

Getting Started

If you want to set up a similar workflow:

1. Set up automated publishing (see my previous post)
2. Enable MCP in your AI agent (Cursor, Claude Desktop, etc.)
3. Configure GitHub MCP server with repository access
4. Define publishing contracts for governance
5. Start publishing from your conversations

The technical details are straightforward, but the impact on productivity and knowledge capture is profound.

Conclusion

The intersection of AI agents, MCP protocols, and automated CI/CD creates a new paradigm for technical publishing. By building on the existing GitHub Actions automation and adding MCP as the entry point, we eliminate context switching and reduce friction.

This isn’t just about automating blog posts—it’s about preserving the flow state of technical discovery and making knowledge sharing as natural as having a conversation.

The future of technical documentation is here, and it’s conversational.

This post was created and published using the exact workflow described above—from a discussion about workflow automation to a live blog post, all without leaving the conversation context.

As a long-time podcaster, I’ve always enjoyed sharing my thoughts and ideas through audio. While the world of video content—and the role of a YouTuber—has its allure, the complexities of video editing have kept me anchored in the realm of podcasting. My journey has involved leveraging platforms like Spotify Creator (formerly Anchor) for hosting and distributing my recordings. This platform offers a wide array of features for free, including audio recording, editing capabilities, and automatic promotion to Spotify.

However, I sought a more comprehensive solution, one that would allow me to listen to my own podcast while driving, using the Podcast app on my CarPlay device. To achieve this, I ventured into publishing on Apple Podcasts (podcastsconnect.apple.com), which also offers free hosting. With a self-designed cover and episodes uploaded, I was set—or so I thought.

The Challenges of Traditional Podcasting

Despite having the technical setup, I faced significant challenges:

• Consistency: Maintaining a regular publishing schedule proved difficult.
• Voice Quality: My voice quality was inconsistent, affecting listener engagement.
• Content Preparation: Crafting well-structured episodes without improvisation was challenging.
• Enhancements: Incorporating background music and other audio elements to enrich the listening experience required additional effort.

These hurdles led to my podcast being suspended for approximately two years. I found myself in need of a solution that could simplify the process and revitalize my passion for podcasting.

Discovering NotebookLM: An AI-Powered Podcasting Tool

Recently, I stumbled upon NotebookLM (notebooklm.google.com), an innovative application developed by Google. NotebookLM harnesses the power of artificial intelligence to generate podcast content. Users can provide a topic and related documents, and the AI takes over, creating engaging podcast episodes.

My Experience with NotebookLM

Intrigued, I decided to give NotebookLM a try. The results were nothing short of astounding:

• Effortless Production: The AI effortlessly generated a half-hour episode featuring two speakers discussing the topics in English.
• Enhanced Content: It went beyond the provided information, utilizing search engines to gather additional relevant data from the internet.
• Quality Output: The quality of the generated content was exceptionally high, surpassing what I could produce on my own.
• Incorporated Music: Appropriate background music was added, enhancing the overall listening experience.
• Cost-Free: All these features were available entirely for free.

A Case Study: Deep Dive into TiDB

To put NotebookLM to the test, I created an episode about TiDB, a product developed by my current employer. The process was seamless, and the final product was impressive. You can listen to the episode here: Deep Dive into TiDB.

Conclusion

The integration of AI into podcast creation through tools like NotebookLM has the potential to revolutionize the way we produce content. It removes many of the barriers that podcasters face, such as time constraints, technical challenges, and the need for consistent quality.

For anyone looking to start or rejuvenate their podcast without the traditional hassles, I highly recommend giving NotebookLM a try. It’s remarkable to see how AI can not only match but enhance human capabilities in creative endeavors.

I hope this helps! Let me know if there’s anything you’d like to add or modify in your blog post.

Table of Contents

• Introduction to Ollama
  • A Popular Choice
  • Ease of Use
  • Built with Golang
• My Practices with Ollama
  • Preferred Models
    • Llama 3.1
    • Mistral
    • Phi-3
    • Qwen-2
  • Hardware Constraints
• Exploring UIs for Ollama
  • OpenWebUI
  • Page Assist
  • Enchanted
  • AnythingLLM
  • Dify
• Diving into llamaindex
• Experimenting with Candle
• Conclusion

Introduction to Ollama

A Popular Choice

Ollama has rapidly become a favorite among developers interested in local LLMs. Within a year, it has garnered significant attention on GitHub, reflecting its growing user base and community support.

Ease of Use

One of Ollama’s standout features is its simplicity. It’s as easy to use as Docker, making it accessible even to those who may not be deeply familiar with machine learning frameworks. The straightforward command-line interface allows users to download and run models with minimal setup.

Built with Golang

Ollama is written in Golang, ensuring performance and efficiency. Golang’s concurrency features contribute to Ollama’s ability to handle tasks effectively, which is crucial when working with resource-intensive LLMs.

My Practices with Ollama

Preferred Models

Llama 3.1

I’ve found that Llama 3.1 works exceptionally well with Ollama. It’s my go-to choice due to its performance and compatibility.

Mistral

While Mistral also performs well, it hasn’t gained as much popularity as Llama. Nevertheless, it’s a solid option worth exploring.

Phi-3

Developed by Microsoft, Phi-3 is both fast and efficient. The 2B parameter model strikes a balance between size and performance, making it one of the best small-sized LLMs available.

Qwen-2

Despite its impressive benchmarks, Qwen-2 didn’t meet my expectations in practice. It might work well in certain contexts, but it didn’t suit my specific needs.

Hardware Constraints

Running large models on hardware with limited resources can be challenging. On my 16GB MacBook, models around 7B to 8B parameters are the upper limit. Attempting to run larger models results in performance issues.

Exploring UIs for Ollama

Enhancing the user experience with UIs can make interacting with local LLMs more intuitive. Here’s a look at some UIs I’ve tried:

OpenWebUI

OpenWebUI offers a smooth and user-friendly interface similar to Ollama’s default UI. It requires Docker to run efficiently, which might be a barrier for some users.

• Features:
  • Basic Retrieval-Augmented Generation (RAG) capabilities.
  • Connection to OpenAI APIs.

Page Assist

Page Assist is a Chrome extension that I’ve chosen for its simplicity and convenience.

• Advantages:
  • No requirement for Docker.
  • Accesses the current browser page as input, enabling context-aware interactions.

Enchanted

Enchanted is unique as it provides an iOS UI for local LLMs with support for Ollama.

• Usage:
  • By using Tailscale, I can connect it to Ollama running on my MacBook.
  • Serves as an alternative to Apple’s native intelligence features.

AnythingLLM

AnythingLLM offers enhanced RAG capabilities. However, in my experience, it hasn’t performed consistently well enough for regular use.

Dify

Dify is a powerful and feature-rich option.

• Pros:
  • Easy to set up with an extensive feature set.
• Cons:
  • Resource-intensive, requiring Docker and running multiple containers like Redis and PostgreSQL.

Diving into llamaindex

llamaindex is geared towards developers who are comfortable writing code. While it offers robust functionalities, it does have a learning curve.

• Observations:
  • Documentation is somewhat limited, often necessitating diving into the source code.
  • The llamaindex-cli tool aims to simplify getting started but isn’t entirely stable.
    • Works seamlessly with OpenAI.
    • Requires code modifications to function with Ollama.

Experimenting with Candle

Candle is an intriguing project written in Rust.

• Features:

  • Uses Hugging Face to download models.
  • Simple to run but exhibits slower performance compared to Ollama.

• Additional Tools:

  • Cake: A distributed solution based on Candle, Cake opens up possibilities for scaling and extending use cases.

Conclusion

Exploring local LLMs has been an exciting journey filled with learning and experimentation. Tools like Ollama, llamaindex, and Candle offer various pathways to harnessing the power of LLMs on personal hardware. While there are challenges, especially with hardware limitations and setup complexities, the control and privacy afforded by local models make the effort worthwhile.

Feel free to share your experiences or ask questions in the comments below!