joshuaclanton.dev

Introducing recon - a CLI tool to gather context for LLMs

2024-05-09T00:00:00+00:00

Introducing recon - a CLI tool to gather context for LLMs

I use large language models like ChatGPT and Claude Opus a lot. No. More than that. A lot a lot.

I use them on my coding side projects, on my writing projects, at my day job, as well as for personal things like organizing my D&D campaign.

But one problem I'm constantly running into is that there are things I'd like to ask of an AI, but either there is a ton of data or it's spread all over the place. For example, if I'm working on RPG Portrait, I may want to discuss growth rates and have it help me prioritize my tasks accordingly. But the growth rates are in a Postgres database, the tasks are in GitHub issues, and it probably needs a bit of the app's source code too.

That's where recon comes in.

The basics

Recon is a command-line tool that makes it easy to gather context from various sources and feed it to an LLM as a single, coherent prompt. With a simple command, you can recursively gather text from files and directories, fetch additional information from URLs, and pipe it all to your AI assistant of choice.

Here's a simple example:

recon --files ./src/landing-pages \
  --urls https://example.com/rules-for-landing-page-copy \
  --prompt "Evaluate our landing pages against these rules" \
  | llm

This command will:

Recursively read all files in the ./src/landing-pages directory
Fetch the text from the URL https://example.com/rules-for-landing-page-copy
Combine all the text (with their respective names) into a single prompt
Pipe the prompt to the llm command

Side note: If you're not using Simon Willison's excellent llm CLI tool, you probably should be.

But even if you're not using llm, you can still use recon to gather context and feed it to a model. It supports a --clipboard command for when you want to paste the prompt into a web-based chat interface.

Getting fancy

The --files and --urls flags are handy for ad-hoc types of queries, but recon also supports a configuration file that allows you to define named sources and prompts. This makes it easy to reuse the same sources across multiple queries.

// .recon.config.mjs
export default {
  commands: {
    // The key is the name of the command
    docs: {
      gather: {
        files: ['./docs'],
        urls: ['https://example.com/some-more-docs']
      }
    }
  }
};

Now I can run the following command:

recon docs \
  --prompt "What's the procedure for multi-stage migrations?" \
  --clipboard

Getting fanciest

Recon also supports defining your own custom "Recon agents" that can gather text from any source you can imagine. For example, you could write an agent that fetches text from a Google Sheet, a database, or even a proprietary API.

// This is a hypothetical recon agent for querying a database
import myDbAgent from './myDbAgent';

export default {
  agents: [myDbAgent]
  commands: {
    growth: {
      // The default prompt for this command
      prompt: "How are we doing on our growth goals?",
      gather: {
        // The default set of files to gather information from
        files: ['./docs/business-plan.md'],
        // The default set of urls to gather information from
        urls: ['https://example.com/'],
        // This tells myDbAgent how to gather its information
        myDb: {
          query: 'SELECT COUNT(*) FROM users',
        },
        // Additional notes to pass along with the prompt.
        // This is the built in `notes` agent
        notes: `REMEMBER: All replies should be in business-speak.
                The more synergy, the better.`,
      }
    },
  }
};

Future plans

I have a lot of ideas for improving recon. Some are obvious, like adding more built-in recon agents. One upcoming feature I'm particularly excited about is letting custom agents register their own CLI flags. This would make the CLI's ad-hoc querying capabilities even more powerful.

Wrapping up

It's still early days for Recon, but I use it every day and it's already saved me a ton of time. I hope that it can do the same for some of you!

If you're interested in trying it out or contributing, you can find it on GitHub.

How to Build an Eleventy Plugin

2020-10-06T00:00:00+00:00

How to Build an Eleventy Plugin

Eleventy is an increasingly popular static site generator, thanks to the fact that it is both very customizable, and comes with a good set of defaults to let you get up and running quickly. And, most relevant to us, it also supports a simple plugin system which allows sharing customizations with others.

The heart of Eleventy's configurability lies in the optional .eleventy.js file. It is there that you can override default configuration, add additional filters to your templating language, and change just about anything else. If you don't already have one, go ahead and create it.

module.exports = (eleventyConfig) => {
};

You'll note that we are exporting a function that takes in an eleventyConfig object, and does nothing with it, leaving all the defaults in place.

Suppose that as part of our site we want to include each article author's Gravatar image. To do that, we can add a custom filter to our configuration. Let's add the skeleton of that filter.

module.exports = (eleventyConfig) => {
  eleventyConfig.addFilter('gravatarUrl', () => {
    
  });
};

Now, the way that Gravatar works is by serving up an image named after the MD5 hash of the user's email address. For example, the image url of foo@bar.com would be https://www.gravatar.com/avatar/f3ada405ce890b6f8204094deb12d8a8.

We'll need to transform the author's email address into an MD5 hash, so let's install the md5 package with npm install --dev md5. And then let's fill out the logic of the filter.

const md5 = require('md5');

module.exports = (eleventyConfig) => {
  eleventyConfig.addFilter('gravatarUrl', (email) => {
    const hash = md5(email.trim());
    return `https://www.gravatar.com/avatar/${hash}`;
  });
};

Now you'll have the gravatarUrl filter available to use anywhere in your layouts. Here is an example of using it in the Liquid templating language.

<img src="{{ authorEmail | gravatarUrl }}" />

We've got a working filter, but suppose that we're actually building a bunch of sites with Eleventy, and we're going to need this functionality again. We could just copy and paste the code everywhere. But we could also turn it into a plugin and publish it to npm so that others can easily use it.

Let's make the code change to convert it into a plugin.

const md5 = require('md5');

const gravatarPlugin = (eleventyConfig) => {
  eleventyConfig.addFilter('gravatarUrl', (email) => {
    const hash = md5(email.trim());
    return `https://www.gravatar.com/avatar/${hash}`;
  });
}

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(gravatarPlugin);
};

You'll see that instead of directly calling addFilter in our configuration function, we define a plugin function on line 3. That function takes in the Eleventy config object and does the work of adding the filter. And then on line 11 we add the plugin. At this point all we need to do is extract the function into a separate package.

So let's create a new directory for our package. Maybe something like eleventy-plugin-gravatar. Then we'll npm init. Next we create an index.js file to copy our plugin into. Make sure that we install md5 as a dependency of our plugin package: npm install md5.

We update our new packages index.js to the following:

const md5 = require('md5');

module.exports = (eleventyConfig) => {
  eleventyConfig.addFilter('gravatarUrl', (email) => {
    const hash = md5(email.trim());
    return `https://www.gravatar.com/avatar/${hash}`;
  });
}

Then we update our .eleventy.js file to the following:

const gravatarPlugin = require('eleventy-plugin-gravatar');

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(gravatarPlugin);
};

To test it out locally, in the plugin directory, type npm link. And then in your Eleventy site's directory, run npm link eleventy-plugin-gravatar. Start your Eleventy dev server up and you should see everything working.

At this point, all you need to do is publish the package to npm. For detailed instructions on that, see the npm documentation.

Congratulations! If you made it this far, you've created your own plugin, made it into it's own package, and maybe even published it.

Like this post? Subscribe to get the next one in your feed reader!

A New Site and a New Experiment - Studying in Public

2020-09-29T00:00:00+00:00

A New Site and an Experiment with Studying in Public

It has been quite a while since I hand-crafted a site for myself. The last time was when I built A Drip of JavaScript way back in 2015. I've been doing front-end coding non-stop since then, but exclusively for my day job.

My goals for the site were:

Easy authoring
Easy publishing
A sophisticated visual style that uses typography to good effect
To make it easier to study in public - More on that later.

Authoring

For authoring, I chose Eleventy. I had heard good things about how it was easy to use and also easy to customize. I found these to be mostly true. The one thing that tripped me up was figuring out which templating language to use. Because Eleventy supports several templating languages out of the box, it took me some time to settle on one which I found intuitive (Nunjucks).

Once I was past that, the docs and the occasional Google search were more than sufficient for me to work through everything else quickly. Caveat: Someone new to front-end development could easily get lost in all the options.

Publishing

For publishing, I went with Netlify. Their reputation for ease of use was great. And it wasn't an exaggeration. After creating an account and connecting it with my domain name and GitHub repository, Netlify automatically detected that I was using Eleventy and suggest default publishing options, which I accepted. About one minute later, the first version of the site was live. ffffadflajadflkajf

Design

I used Tufte CSS as the basis for the visual design, but customized it pretty extensively.

The most obvious customization is in the typography. The font size is substantially smaller to provide better information density. And rather than using Tufte CSS's very traditional serif fonts, I opted to use Mozilla's Open Source Fira Sans, augmented by Fira Code.

The result, I hope, is a design that balances appearing both very traditonal and very modern.

Beauty of style and harmony and grace and good rhythm depend on simplicity

Plato — Republic, Book 3

Studying in Public

My final goal was to make it easier for me to share the results of my studies. I'm constantly reading and studying, but haven't done much sharing in a while.

I have done it in the past with blog posts and the Drip of JavaScript newsletter. But it takes a huge amount of effort that to convert the raw materials of my studies into something polished enough to present as a cohesive article.

So instead, I'm doing something new. I'm taking the things I'm learning and writing them down in a Foam notebook. My notes are rough, unfinished, and probably wrong occasionally. But I can publish them without thinking too hard. And I suspect that's the most important thing.

I hope that others find it helpful, but I also know that I'm going to enjoy having an easy place to find my notes on the go.

Here's to a new site and to trying new things!