Houston Agent

The houston agent is a small toy terminal-based coding agent, powered by Claude Sonnet 5.

• Animated Houston companion following you during your session.
• Prompt writing shortcuts (Ctrl+A/E, Ctrl+Left/Right, Ctrl+Backspace, etc.)
• Prompt history (Up, Down) with pending draft preservation.
• Prompt interruption with double Esc.
• Pretty Markdown output.
• Read-only project inspection tools: list_directory, read_file, and search_files.
• Project-local Agent Skills support in .skills/ and .agents/skills with model-driven activation.
• Agent skill activation with slash commands and active skill display in the interface.

Setup

Install dependencies:

pnpm install

Build the project:

pnpm run build

Rename .env.example to .env and set ANTHROPIC_API_KEY with your API key:

ANTHROPIC_API_KEY=<YOUR_API_KEY>

Start the agent:

pnpm start

Demo

After following the setup instructions, run pnpm start and start prompting away.

Or, use one of these example prompts:

Review src/app.tsx for React best practices. Answer me with Markdown and code blocks with any findings.

/grill-me Grill my plan to add a /help command to this Houston agent.

This is my first time in the repository. Help me understand it and introduce me to the most relevant entry points.

More

Time spent

I spent around 26 hours from start to finish across 4 days. Some of this time was improving the overall experience in a way that wasn't required but felt important to include, even if it was not meant to be a production-ready coding agent from start. For only the relevant, functional bits, it took me around 16 hours.

Challenges

I believe "functional" should mean more than doing the bare minimum, so one of the things I invested quite a bit of time in was the prompt writing experience. Since it runs on a terminal, there's a lot that desktop and web environments give you for free that you have to implement from scratch: scrolling, keyboard shortcuts, cursor movement, and avoiding layout shifts are some examples. I can't deny it was very satisfying to see how much adding these features aggregated to the final experience.

Something that was trickier than it sounds was how emojis behaved in the prompt input. Originally, moving or deleting across an emoji could cause it to render weird "?" characters. The issue was that emojis and other composed Unicode characters can be represented by more than one raw UTF-16 code unit. That is, the prompt input needed to be grapheme-aware, so cursor movement and deletion operate on the visible character, rather than a single JavaScript string index.

It also took me some time to decide which approach to use for activating Agent Skills. I initially implemented skills harness-side with fuzzy skill matching, but its accuracy for detecting when to use a skill was not great. I ended up going with the more complex approach of model-driven activation, where Claude chooses when to activate a skill through the activate_skill tool. That took more time to build and review, especially because it interacts with Claude's streaming response flow and tool-use loop.

Tool calling was also interesting. It made me realize how much the tools a harness adds affects the quality of answers you get, especially when used in conjuction with Agent Skills. Initially, I added Agent Skills with no tools, meaning most skills could not do anything with the user's code. Adding just directory listing, file search and file reading immediately made the agent much smarter. It paid off because skills could then react to the actual codebase and talk about it with useful context.

Of course, the biggest challenge was not getting too attached to the project. If an entire animated Houston companion is not enough proof, I had a fun time making this and probably wouldn't stop adding features till I was satisfied and it matched everything I expect from a production-ready coding agent. But that would be going beyond the goal, and self-control is an important skill to have.