Cogsmith

Inspiration

I started CogSmith because I needed a calculator to do some garage math for me.

In my downtime I’ve started converting older MTBs into cool single-speed bikes, I find the tinkering in my garage really relaxing. The challenge is I'm constantly trial-and-erroring to figure out good combinations of gears to use, and I don't have a million gears to select from. I only have what the bike came with.

There is math to help with this, but after crunching these numbers manually one too many times, I built a tool to handle it. I ended up fully fleshing out CogSmith because the calculator worked incredibly well for my own projects, and I was looking for a practical excuse to learn about vibe coding.

What it does

A rider enters information about their project bike, including wheel size, chainstay length, available chainrings and rear cogs, desired gearing, and dropout adjustment range.

CogSmith then evaluates the possible combinations and calculates the Goldilocks combination for the rider.

Instead of only calculating a gear ratio, CogSmith tries to answer the more useful question:

"Can I actually build this combination on my bike?"

CogSmith also supports WebMCP, allowing AI assistants to interact directly with the calculator. This is great as sometimes in the garage, your hands are filthy and the AI assistant can do lookups for you.

How I built it

I have a background in DevOps and infrastructure type scripting, so I wanted to use this as a chance to learn some vibe coding. For tools I wanted to do this as cheaply as possible so the best fit was to build this on GitHub, for its CI/CD pipelines and its static page hosting. It also integrated well with workflows I had used in the past AND worked well with GPT Work and Codex.

CogSmith was built as a static web application using HTML, CSS, and JavaScript. It slowly grew from an all-in-one HTML file into something broken out into components, ultimately getting to a point where resources were broken up into testable pieces and I started using GitHub releases.

As the project matured so did its architecture. It focuses on two areas now. A tool for humans and a tool for robots.

Human interface → CogSmith calculation engine

and

AI through WebMCP → CogSmith calculation engine

Both paths use the same underlying logic, so an AI recommendation is based on the same calculations that appear in the browser. CogSmith exposes WebMCP tools that allow an AI to read the current bike configuration, calculate possible gearing combinations, and display a selected setup back in the user interface.

One of the core measurements CogSmith uses is gear inches:

G = D × (T_f / T_r)

where:

G is gear inches
D is wheel diameter
T_f is the number of teeth on the front chainring
T_r is the number of teeth on the rear cog

CogSmith then combines that gearing calculation with chain-length and axle-position calculations to determine whether the setup will physically fit within the available dropout range.

We also added automated tests and CI validation around the calculator and WebMCP interfaces so changes can be tested before being deployed.

Challenges I ran into

Honestly most of the infrastructure and pieces of the website were well understood and commonly used, however I started to face challenges with understanding how MCP worked and pivoting to how WebMCP works.

WebMCP isn't well documented yet and honestly the test frameworks aren't great for it right now. That was the hard part, learning MCP :)

Accomplishments that I'm proud of

I love everything about CogSmith, I've used it for 3 different bikes so far and it saves me from fiddling around with gears.

I'm most amazed and proud of learning about WebMCP. I'd been familiar with taking a function and exposing it as an API, but I never knew you could do something similar like taking a math formula and passing it to an AI. I think that's cool. It's like APIs for LLMs :D

What I learned

I had already learned that the voice assistant was useful in the garage, like "tell me the wheel lug nut torque rating for a 2018 GMC 1500 truck" or "I need 50:1 fuel mix for my outboard motor, I have 5L of gas, how much oil do I add", but I never knew I could build a tool and plumb it into GPT. I had always thought GPT needed to search the internet to find this knowledge.