DEV Community: Amine Ben hammou

How to Chat with Gemini 2.5 Pro from VSCode via AI Studio (Free and Unlimited)

Amine Ben hammou — Tue, 15 Apr 2025 11:08:50 +0000

The Gemini 2.5 Pro is a good model, and it's free to use on Google AI Studio, but the UI is not very user-friendly in my opinion. What if I could chat with it from VSCode? Check out the following demo:

As you can see, the feature is as follows:

To start a new chat, I simply hit a shortcut, I choose ctrl+shift+i.
A new chat file is created and opened in the editor.
I type my message in the markdown file, and press the shortcut ctrl+shift+i.
The file is updated with a loading message.
After a few seconds, the file is updated with the response from Gemini.
Then I can continue to chat like that.

Ok, are you wondering how it works? let's see how I implemented it step by step.

1. Create a new chat file
2. Updating the chat file
3. Interacting with AI Studio in the browser
- 3.1. Attempt 1: Controlling the browser with Playwright
- 3.2. Attempt 2: Running a local server and injecting a JS snippet in the browser
- 3.3. Attempt 3: Creating a browser extension
4. Sending the message and getting the response in the browser
5. Streaming the response to the file

1. Create a new chat file

The first step is to create a new chat file when I press ctrl+shift+i and open it.

To implement this, I used the Neat Scripts extension that I built a while back in this article. You don't have to read that article to follow with this one, I will explain how it works here.

The first thing to do it to add the following keybinding to VSCode:

{
  "key": "ctrl+shift+i",
  "command": "neat-scripts.run",
  "args": {
    "script": "/absolute/path/to/chat.ts"
  }
}

This tells VSCode to run our chat.ts script using the Neat Scripts extension when the ctrl+shift+i shortcut is pressed.

So let's create the chat.ts script.

#!/usr/bin/env bun

console.log("Hello World");

The first line is called a shebang. It tells the system which interpreter to use to run the script. In this case, I am using Bun. I also need to make the file executable for that to work; on Linux/Mac, you can do that with the following command:

chmod +x chat.ts

Now if I press ctrl+shift+i, the script will run but nothing will happens yet. Let's make it create a new chat file and tell VSCode to open it.

#!/usr/bin/env bun

async function new_chat() {
  const chat_path = `/tmp/${Date.now()}.chat.md`;
  await Bun.write(chat_path, "");
  console.log(
    JSON.stringify({
      command: "neat-scripts.files.open",
      args: { path: chat_path },
    })
  );
}

await new_chat();

Now when the script is run, it will create a new chat file and tell VSCode to open it by printing the following JSON line:

{"command": "neat-scripts.files.open", "args": { "path": "/tmp/<timestamp>.chat.md" }}

The Neat Scripts extension receives this JSON line, and calls the neat-scripts.files.open to open the file.

That's it, now we are creating a new chat file and opening it.

2. Updating the chat file

if we are already inside a chat file, and we press ctrl+shift+i, we don't want to create a new chat file, instead, we want to update the current one.

So when our chat.ts script is run, it needs to know the current filename. Luckily, the Neat Scripts extension passes the following JSON object to the stdin of the script:

{
  "workspace_path": "/path/to/your/current/workspace",
  "file": "/path/to/your/current/open/file",
  "selections": [ // list of current selections/cursors
    {
      "start": { "line": 1, "col": 1 },
      "end": { "line": 1, "col": 1 }
    }
  ]
}

So, let's update our chat.ts read the stdin and check the current file:

#!/usr/bin/env bun

async function new_chat() {
  // ... same code as before
}

async function update_chat(chat_path: string) {
  await Bun.write(chat_path, "Updating ...");
}

async function main() {
  const input = await Bun.file("/dev/stdin").json();
  const filename = input.file;
  if (filename.endsWith(".chat.md")) {
    await update_chat(filename);
  } else {
    await new_chat();
  }
}

main().catch(console.error);

Now if the current file is a chat file, the script will write "Updating ..." to it.

Let's now improve this updating logic, the update_chat function should do the following:

Read the current content of the chat file
Split the content into messages
Take the last message and send it to Gemini on AI Studio (we will mock this part for now)
Receive the response from Gemini (we will mock this part for now)
Add the response to the chat file

To separate messages in the chat file, let's use the following format:

message 1

---chat-separator---

message 2

---chat-separator---

...

Here is the resulting code of the update_chat function:

import { setTimeout } from "timers/promises";

const chat_separator = `\n\n---chat-separator---\n\n`;

async function update_chat(chat_path: string) {
  const content = await Bun.file(chat_path).text();
  await Bun.write(chat_path, `${content}${chat_separator}Loading...`);

  const last_message = content.split(chat_separator).at(-1)!;
  const response = await send_message(last_message);
  await Bun.write(chat_path, `${content}${chat_separator}${response}${chat_separator}`);
}

async function send_message(message: string) {
  await setTimeout(5000);
  return "Fake response";
}

Now when I type something in the chat file, and press ctrl+shift+i, I see

My message

---chat-separator---

Loading...

Then after 5 seconds, I see

My message

---chat-separator---

Fake response

---chat-separator---

So the chat updating logic is working.

3. Interacting with AI Studio in the browser

This is the most interesting part. The send_message function needs to send the message on the AI Studio UI, wait for the response, then return it as markdown.

You may ask "Why don't you just use the API?". The API currently has a ratelimit of 25 free requests per day, which is low. While the number of messages I can send via the AI Studio interface seems unlimited.

3.1. Attempt 1: Controlling the browser with Playwright

My first idea was to run an instance of Chrome and control it using Playwright. So I created a file browser.ts and wrote the following code to:

Run an instance of Chrome with headless: false so that I can see what's happening.
Open Google.
Login using my credentials that I stored in .env file.
Open AI Studio.
Write "Hello there!" in the chat.
Send a message.

import { env } from "bun";
import { setTimeout } from "timers/promises";
import { chromium, devices } from "playwright";

const browser = await chromium.launch({ headless: false });
const context = await browser.newContext(devices["Desktop Chrome"]);
const page = await context.newPage();

await page.goto("https://google.com/");
await page.click('[aria-label="Connexion"]');
await page.fill('[name="identifier"]', env.GOOGLE_EMAIL!);
await page.click("#identifierNext");
await page.fill('[name="Passwd"]', env.GOOGLE_PASSWORD!);
await page.click("#passwordNext");
await setTimeout(3000);
await page.goto("https://aistudio.google.com/prompts/new_chat");
await page.click('button[aria-label="close"]');
await page.click('textarea[aria-label="Type something"]');
await page.fill('textarea[aria-label="Type something"]', "Hello there!");
await page.click("run-button");

All steps worked fine, but when the Send button is clicked, I get a permissions error. it seems that the AI Studio backend blocks requests from automated browsers.

I could think of ways to bypass that, but I decided to try a different approach.

3.2. Attempt 2: Running a local server and injecting a JS snippet in the browser

The second idea was to create a server on my localhost and insert a client JS code to communicate with it using websockets.

3.2.1. Creating the HTTP server

Let's create a server when send_message is called, it will simply print a message when the client connects or sends a message for now.
I will also close the server after 30 seconds and return a fake response.

const server_port = 3331;

async function send_message(message: string) {
  const server = Bun.serve({
    port: server_port,
    websocket: {
      open(ws) {
        console.log("WebSocket connection opened");
      },
      message(ws, message) {
        console.log("Message received:", message);
      },
    },
    fetch(req, server) {
      if (req.url.endsWith("/chat")) {
        server.upgrade(req);
        return;
      }
      return new Response("Hello World");
    },
  });
  await setTimeout(30_000);
  await server.stop();
  return "Fake response";
}

Now when I type a message in the chat file and press ctrl+shift+i, then visit http://localhost:3331, I see "Hello World". So the server is running. But I can't see what it prints because I don't have access to stdout of the script.

Let's replace the console.log calls with the following log function; it will print a JSON command that shows the message as a notification on VSCode.

function log(message: string) {
  console.log(
    JSON.stringify({
      command: "neat-scripts.notifications.info",
      args: { message },
    })
  );
}

3.2.2. Creating the client

Let's write the JS code that will connect to the server from the browser.

(function() {
  const ws = new WebSocket('ws://localhost:3331/chat');
  ws.onmessage = (event) => {
    console.log('Message received:', event.data);
  };
})();

When I paste the JS code into the browser console on the http://localhost:3331 page, I see that the socket connection is opened and the message sent by the server is received by the client.
But pasting the same code in the AI Studio page doesn't work:

First I had CORS error that I fixed by adding some headers to the server response.
Then I had a Mixed Content error because AI Studio is on a secure protocol (HTTPS) while my local server is on HTTP.

As this point I could think of the following options:

Create a local domain and generate SSL certificates for it using Let's Encrypt, and use it for my server.
Create a tunnel to my local server using a tool like ngrok.
Create a browser extension to communicate with my local server using a background service worker.

I decided to go with the browser extension option. Why? because it's a chance to learn more about service workers in the browser.

3.3. Attempt 3: Creating a browser extension

3.3.1. Creating a separate server

To make testing easier, instead of having our chat.ts script start the server each time we call it. Let's create the server separately and keep it running in the background. To do that, I created server.ts:

Bun.serve({
  port: 3331,
  websocket: {
    open(ws) {
      console.log("WebSocket connection opened");
    },
    message(ws, message) {
      console.log("Message received:", message);
    },
  },
  fetch(req, server) {
    if (req.url.endsWith("/chat")) {
      server.upgrade(req);
      return;
    }
    return new Response("Hello World");
  },
});

3.3.2. Creating the browser extension

With that server running, let's create the browser extension. I created the following files:

extension/
  manifest.json
  worker.js
  content.js

The manifest.json file describes the extension:

{
  "manifest_version": 3,
  "name": "Gemini VSCode Chat",
  "version": "1.0",
  "description": "Chat with Gemini from VSCode",
  "permissions": [],
  "host_permissions": [
    "https://aistudio.google.com/*"
  ],
  "background": {
    "service_worker": "worker.js"
  },
  "content_scripts": [
    {
      "matches": ["https://aistudio.google.com/prompts/*"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ]
}

The important parts are:

We are using manifest version 3.
We don't require any special permissions.
host_permissions specifies that we need access to the AI Studio domain.
background specifies the background service worker file.
content_scripts specifies the content script file (the JS code that will be injected into the AI Studio page).

Next we create the files worker.js and content.js. Let's have them simply console.log something.

worker.js:

console.log("Background service worker started.");

content.js:

console.log("Content script loaded.");

To test the extension, we can load it in Chrome:

Open Chrome and go to chrome://extensions/.
Enable "Developer mode".
Click "Load unpacked" and select the extension directory.

Now when I visit the AI Studio page, I see the "Content script loaded." message in the console. So our extension is working.

3.3.3. Socket communication between the service worker and the local server

Next step is to implement the socket communication between the service worker and the local server.

worker.js:

const ws = new WebSocket("ws://localhost:3331/chat");
ws.onmessage = (event) => {
  console.log("Message received:", event.data);
  ws.send("Hello from service worker");
};

server.ts:

Bun.serve({
  port: 3331,
  websocket: {
    open(ws) {
      console.log("WebSocket connection opened");
      ws.send("Hello from server");
    },
    message(ws, message) {
      console.log("Message received:", message);
    },
  },
  // ...
});

The communication will happen as follows:

Service worker opens a WebSocket connection to the server (new WebSocket("ws://localhost:3331/chat")).
Server receives the connection, prints "WebSocket connection opened" and sends a message "Hello from server". (The open callback).
Service worker receives the message, prints "Message received: Hello from server" and sends a response "Hello from service worker".
Server receives the response, prints "Message received: Hello from service worker".

So after restarting the server and reloading the extension, I see the following messages:

the server console:

WebSocket connection opened
Message received: Hello from service worker

the service worker console:

Message received: Hello from server

3.3.4. Communication between the service worker and the content script

The communication between the service worker and the content script can be done with the chrome.runtime.sendMessage, chrome.runtime.onMessage, chrome.tabs.query and chrome.tabs.sendMessage APIs.

Here is a quick explanation of the usage of each one of them:

chrome.runtime.sendMessage:

Sends a message from the content script to the service worker.

const response = await chrome.runtime.sendMessage({ message: "Hello from content script" });

if the service worker sends back a response, it will be available in the response variable.

chrome.tabs.sendMessage:

Sends a message from the service worker to the content script on a specific tab.

const response = await chrome.tabs.sendMessage(tabId, { message: "Hello from service worker" });

The tabId identifies the tab where the content script is running. One way to get it is from the sender object in the chrome.runtime.onMessage listener.

chrome.runtime.onMessage:

Listens for messages sent via runtime.sendMessage or tabs.sendMessage, can be used in both content scripts and service workers.

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  console.log("Message received:", message);
  console.log("sender tabId:", sender.tab?.id);
  // handle the message
});

Note that the sender.tab is only defined if the sender is a content script. In that case it contains the tab object from which we can grab the id to use with chrome.tabs.sendMessage.

Now let's use these functions to implement the following simple communication between the service worker and the content script:

When the content script is first loaded, it sends a "Hi" message to the service worker.
The service worker receives the message, saves the tab id for the future, and sends a response "Welcome".
After 10 seconds, the service worker sends a "Are you still there?" message to the content script.
The content script receives the message and responds with "Yes!".

content.js:

console.log("Gemini VSCode Chat: Content script loaded.");

(async () => {
  const response = await chrome.runtime.sendMessage("Hi");
  console.log("Response:", response);
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    console.log("Message received:", message);
    if (message === "Are you still there?") {
      sendResponse("Yes!");
    }
  });
})();

worker.js:

console.log("Background service worker started.");

(async () => {
  let tabId = null;
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    console.log("Message received:", message);
    if (message === "Hi") {
      tabId = sender.tab?.id;
      sendResponse("Welcome");
    }
  });

  setTimeout(async () => {
    if (tabId) {
      const response = await chrome.tabs.sendMessage(
        tabId,
        "Are you still there?"
      );
      console.log("Response:", response);
    } else {
      console.log("No tab found!");
    }
  }, 10000);
})();

3.3.5. Putting it all together

Now let's put it all together, here is the complete flow:

Let's implement this full communication, I will mock the part where the content script interacts with the DOM for now, and tackle it in the next section.

content.js

Let's start with the content script since it's the one that should be executed first. It needs to do the following:

Send a message to the service worker (so that it can save the tab id)
Listen for messages from the service worker. When a message is received, it will simply wait 5 seconds then respond with a fake response.

(async () => {
  chrome.runtime.sendMessage("new tab");
  chrome.runtime.onMessage.addListener((message, _, sendResponse) => {
    setTimeout(() => sendResponse("a fake response ..."), 5000);
    return true;
  });
})();

worker.js:

Now let's write the code for the background service worker. It should do the following:

Wait for a message from the content script and save the tab id.
Try to connect to the local server via sockets in a loop. If failed, try again after 1 second.
Once connected, receive the chat message from the server.
Send the chat message to the content script and wait for a response.
Send the response back to the server.

let tabId = null;

async function wait(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function connect_to_server() {
  while (true) {
    await wait(1000);
    try {
      const ws = new WebSocket("ws://localhost:3331/chat");
      await new Promise((resolve, reject) => {
        ws.onopen = resolve;
        ws.onerror = reject;
      });
      return ws;
    } catch {}
  }
}

async function get_server_message(ws) {
  return new Promise((resolve) => {
    ws.onmessage = (event) => {
      resolve(event.data);
    };
  });
}

async function main() {
  chrome.runtime.onMessage.addListener((_, sender) => {
    tabId = sender.tab?.id;
  });
  while (true) {
    while (!tabId) {
      await wait(1000);
    }
    const ws = await connect_to_server();
    const message = await get_server_message(ws);
    const response = await chrome.tabs.sendMessage(tabId, message);
    ws.send(response);
    await wait(1000);
    ws.close();
  }
}

main();

chat.ts

And the last part is the local server code as part of the chat.ts script. The send_message function should do the following:

Create a local server that listens on port 3331.
Listens for socket connections to ws://localhost:3331/chat.
When a socket connection is open, send the message to the client.
Wait for a response from the client.
When a response is received, stop the server and return it.

async function send_message(message: string) {
  return new Promise((resolve) => {
    const server = Bun.serve({
      port: server_port,
      websocket: {
        open(ws) {
          ws.send(message);
        },
        message(_, message) {
          respond(message.toString());
        },
      },
      fetch(req, server) {
        if (req.url.endsWith("/chat")) {
          server.upgrade(req);
          return;
        }
        return new Response("Hello World");
      },
    });
    const respond = async (message: string) => {
      resolve(message);
      await server.stop(true);
    };
  });
}

That's it for the communication between different parts.

At this stage, when I write my message on VSCode and wait about 5 seconds, The "a fake response ..." is added to the chat file. All that remains is to replace this with the actual response from Gemini as markdown.

4. Sending the message and getting the response in the browser

This part can be divided into the following steps:

Writing the message in the textarea and sending it.
Waiting for the response.
Extracting the response as markdown and sending it to the service worker.

4.1. Writing the message in the textarea and sending it

First I inspected the elements in the AI Studio chat page and wrote selectors for the textarea and the send button.

textarea: textarea[aria-label="Type something"].
send button: button[aria-label="Run"].

Then my first attempt was to write the following:

const textarea = document.querySelector('textarea[aria-label="Type something"]');
const button = document.querySelector('button[aria-label="Run"]');
textarea.value = message;
button.click();

But this code doesn't work, the message is inserted in the textarea but the button stays disabled and the click does nothing.

After some experiments, all I needed to do is to dispatch an input event after setting the value of the textarea, and wait a little bit for the button to become enabled.

(async () => {
  const textarea = document.querySelector('textarea[aria-label="Type something"]');
  const button = document.querySelector('button[aria-label="Run"]');
  textarea.value = message;
  textarea.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
  await new Promise(resolve => setTimeout(resolve, 500));
  button.click();
})();

Now the message is sent correctly!

4.2. Waiting for the response

When the send button is clicked, its text changes from "Run" to "Stop", I can do that and wait while the text "Stop" appears in the button.

(async () => {
  // ... previous code
  button.click();
  await new Promise(resolve => setTimeout(resolve, 1000));
  while (button.innerText.indexOf("Stop") !== -1) {
    await new Promise(resolve => setTimeout(resolve, 500));
  }
  console.log("Response received");
})();

4.3. Extracting the response as markdown and sending it to the service worker

For this step, I want to do the following:

Hover over the chat response
Click on the options button (the three dots icon that appears at top right)
Click on the "Copy markdown" item
Inspect the copied text and send it to the service worker

I examined the DOM elements and noticed that each chat message/response is inside an element ms-chat-turn. So I can get the last message element with

const last_message_container = Array.from(document.querySelectorAll("ms-chat-turn")).pop();

The options button is inside that container, I can select it with button[aria-label="Open options"] and click it.

const options_button = last_message_container.querySelector('button[aria-label="Open options"]');
options_button.click();

Then a menu appears with options, I can select the icon inside the "Copy markdown" option and click it.

const markdown_span = document.querySelector('span.copy-markdown-button');
markdown_span.click();

This will insert the markdown text into the clipboard. But will fail if the tab is not focused (which will be the case in my usage). So I need a way to intercept what is being copied to the clipboard and send it to the service worker.

First I need to know which API is used to copy to the clipboard, so I wrote the following code and run it in the browser console:

navigator.clipboard.writeText = (text) => console.log('navigator.clipboard.writeText', text);
navigator.clipboard.write = (data) => console.log('navigator.clipboard.write', data);
document.execCommand = (command, showUI, value) => console.log('document.execCommand', command, showUI, value);
ClipboardEvent.prototype.setData = function(format, data) {
  console.log('ClipboardEvent.prototype.setData', format, data);
};

This will mock the different APIs that could be used and log a message when one is called. Now I simply had to click the "Copy markdown" button and check the console. I saw:

document.execCommand copy undefined undefined

So Google are using the document.execCommand('copy') API to copy to the clipboard, which means that they are selecting the text right before calling that API. Then I can intercept that call and get the selected text.

const original_fn = document.execCommand;
document.execCommand = (...args) => {
  if (args[0] === "copy") {
    const text = document.activeElement.value;
    console.log("Copied markdown", text);
  }
  return original_fn.apply(document, args);
};

This code works when I paste it in the console, but doesn't when I add it to the content script.

After spending some time debugging and readig more about how extensions work, I realized that the content script runs in a different Javascript context than the actual page, they only share access to the DOM. So when I was mocking document.execCommand, I was mocking it in the context of the content script, not the actual page.

So I need to get the copied text only via the DOM. Let's think again what happens when I click the "Copy markdown" button:

A textarea is created, its value is set to the markdown.
The textarea is inserted into the DOM.
The textarea content is selected.
The copy command is executed.

What if I could listen for changes to the DOM and get the inserted textarea, I could then get the markdown by simply doing textarea.value. Luckily there is an API to do exactly that: MutationObserver.

const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    mutation.addedNodes.forEach((node) => {
      if (node.tagName === "TEXTAREA") {
        console.log("Textarea's text", node.value);
      }
    });
  });
});
observer.observe(document.body, { childList: true, subtree: true });

This code will log the text of the textarea when it is added to the DOM.

Putting it all together, the final code for the function that gets the response as markdown is:

async function get_response() {
  const last_message_container = Array.from(document.querySelectorAll("ms-chat-turn")).pop();
  const options_button = last_message_container.querySelector('button[aria-label="Open options"]');
  options_button.click();
  let response = null;
  const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      mutation.addedNodes.forEach((node) => {
        if (node.tagName === "TEXTAREA") {
          response = node.value;
        }
      });
    });
  });
  observer.observe(document.body, { childList: true, subtree: true });
  const markdown_span = document.querySelector("span.copy-markdown-button");
  markdown_span.click();
  await new Promise((resolve) => setTimeout(resolve, 2000));
  while (!response) {
    await new Promise((resolve) => setTimeout(resolve, 500));
  }
  observer.disconnect();
  return response;
}

5. Streaming the response to the file

Right now, we wait for the full response to be streamed to the browser before appending it all at once to the file. It can be better to stream the response to the file as it is received, this way I can start reading the response while it is still streaming.

To do that, I updated the content script to send the current response every 300ms while it's being streamed. Then updated the service worker to send those partial responses to the server, and updated the chat.ts to rewrite the file with each partial response.

I will not bore you with the full code here, you can check it out on GitHub: https://github.com/webNeat/vscode-gemini-chat

Conclusion

This was a fun little project that made me learn new things about Chrome extensions.

Let me know what you think about it, would you use this tool if I make easier to install (proper VSCode and browser extensions)? would you like it to support other AI chats (ChatGPT, Claude, ...)? what other features would you like to see?

You can check the full code on GitHub: https://github.com/webNeat/vscode-gemini-chat

RAG - Implementing the docs commands

Amine Ben hammou — Tue, 28 Jan 2025 14:21:32 +0000

This is the fourth article of a series in which I am building an open source RAG CLI tool. In the previous article we designed the database schema and added a configuration file.

In this article, we will begin to implement the commands for managing documentations: docs add, docs update, and docs remove. Let's start by organizing our code better.

Creating the commands files

To keep our code organized, let's move each command implementation to its own file.

src/
  commands/
    docs/
      add.ts     # Implementation of `rag docs add`
      update.ts  # Implementation of `rag docs update`
      remove.ts  # Implementation of `rag docs remove`
      index.ts   # exports all docs commands
    get.ts       # Implementation of `rag get`
    index.ts     # exports all commands

We only have placeholder implementations for now.

src/commands/docs/add.ts

type Options = { subdir: string; branch: string }
export async function add(name: string, repo_url: string, options: Options) {
  console.log(`Adding documentation ${name} from ${repo_url} with options ${JSON.stringify(options)}`)
}

similarly for docs/update.ts, docs/remove.ts and get.ts.

src/commands/docs/index.ts

export * from './add'
export * from './update'
export * from './remove'

src/commands/index.ts

export * as docs from './docs'
export * from './get'

With that, we can import the commands in the main file src/main.ts:

import * as commands from './commands'

// ...
docs
  .command('add')
  // ...
  .action(commands.docs.add)

docs
  .command('update')
  // ...
  .action(commands.docs.update)

docs.command('remove')
  // ...
  .action(commands.docs.remove)

program
  .command('get')
  // ...
  .action(commands.get)

Implementing the docs commands

Implementing `rag docs add`

rag docs add <name> <repo_url> [--subdir <subdir>] [--branch <branch>]

We want this command to do the following:

clone the repository.
get the markdown files from the specified subdir and branch.
create the documentation in the database and add the files and chunks to it.
if the documentation already exists, show an error message.

Here is the implementation:

type Options = {
  subdir: string
  branch: string
}
export async function add(name: string, repo_url: string, options: Options) {
  if (await db.documentations.has(name)) {
    throw new Error(`Documentation ${name} already exists. Use 'rag docs update ${name}' to update it.`)
  }

  const clone_path = await clone_repo(repo_url, options)
  const documentation = await db.documentations.create({ name, repo_url, ...options })
  const md_files = get_md_files(clone_path)
  for await (const filename of md_files) {
    await add_file_to_documentation(documentation, filename)
  }
}

Notice that I am using some functions that are not implemented yet. The goal is to outline the functions we need and how we are going to use them, then implement them. So far we need:

db.documentations.has: to check if a documentation already exists in the database.
db.documentations.create: to create a new documentation in the database.
clone_repo: to clone a specific branch and sub-directory of a repository and return its path.
get_md_files: to scan a directory recursively for markdown files and return an iterator over their relative paths.
add_file_to_documentation: to split a markdown file into chunks and add them to a documentation in the database.

Before implementing these functions, let's write the code for other commands.

This seems like a lazy thing to do, why don't you finish the implementation of the first command before starting the next one?

Writing the outline code of other commands will give me more visibility on the functions I need to implement. I may find out that I can reuse some functions on multiple commands if I modify their arguments slightly. I will be able to implement these functions once, instead of implementing them for the first command then refactoring them for the second one, and so on.

Implementing `rag docs update`

rag docs update <name> [--repo_url <repo_url>] [--subdir <subdir>] [--branch <branch>]

We want this command to do the following:

get the documentation by name from the database.
if the documentation does not exist, show an error message.
update the documentation with the given options.
clone the repository.
get the markdown files from the updated subdir and branch.
update files and chunks in the database:
- if the database file has the same hash as the new file, do nothing.
- if hashes are different, delete the old file and its chunks and insert the new one.
- if a file does not exist on database, add it.
- if a file exists on database but is not found on the repo, delete it.

This a bit complicated then the previous command, so let's write the code step by step.

We start with this empty function:

type Options = {
  repo_url: string
  subdir: string
  branch: string
}
export async function update(name: string, options: Options) {

}

First we fetch the documentation by name from the database. and throw an error if it does not exist.

export async function update(name: string, options: Options) {
  const documentation = await db.documentations.get(name)
  if (!documentation) {
    throw new Error(`Documentation ${name} not found. Use 'rag docs add ${name}' to create it.`)
  }
}

Then we update the documentation with the given options and clone the repository.

export async function update(name: string, options: Options) {
  // ...
  await db.documentations.update(name, options)
  const clone_path = await clone_repo(documentation.repo_url, documentation)
}

Then we fetch the existing files on the database and define a set to keep track of the seen filenames. This will be useful to detect files that are not found on the repo later.

export async function update(name: string, options: Options) {
  // ...
  const files = await db.files.find({ documentation_id: documentation.id })
  const seen_filenames = new Set<string>()
}

Now we loop over the markdown files on the cloned repo:

export async function update(name: string, options: Options) {
  // ...
  for await (const filename of get_md_files(clone_path)) {

  }
}

We track the filename as seen and find the corresponding file in the database.

export async function update(name: string, options: Options) {
  // ...
  for await (const filename of get_md_files(clone_path)) {
    seen_filenames.add(filename)
    const file = files.find((f) => f.filename === filename)
  }
}

if the file exists on the database, we compare its hash with the new file and skip it if they match. Otherwise, we delete the file and its chunks from the database.

export async function update(name: string, options: Options) {
  // ...
  for await (const filename of get_md_files(clone_path)) {
    // ...
    if (file) {
      const hash = await hash_file(path.join(clone_path, filename))
      if (file.hash === hash) continue
      await db.chunks.remove({ file_id: file.id })
      await db.files.remove({ id: file.id })
    }
  }
}

Finally, if we didn't skip the file, we add it to the database, using the same function we used in the add command.

export async function update(name: string, options: Options) {
  // ...
  for await (const filename of get_md_files(clone_path)) {
    // ...
    if (file) {
      // ...
    }
    await add_file_to_documentation(documentation, filename)
  }
}

Then at the end, we delete the files we didn't see on the repo.

export async function update(name: string, options: Options) {
  // ...
  for await (const filename of get_md_files(clone_path)) {
    // ...
  }
  const unseen_files = files.filter((f) => !seen_filenames.has(f.filename))
  await delete_files_and_chunks(unseen_files)
}

I see some performance optimizations we can do here to make this command faster ...

I know that this implementation is slow. My plan is to have a first working version, do some benchmarking, then demonstrate how we can optimize it and compare the performance before/after.

So in this second command, we reused the following functions from the add command: clone_repo, get_md_files, add_file_to_documentation. And added the following functions:

db.documentations.get: to get a documentation by name from the database.
db.documentations.update: to update a documentation in the database.
db.files.find: to get a list of files from the database.
hash_file: to read a file and compute its hash.
db.chunks.remove: to delete chunks from the database.
db.files.remove: to delete files from the database.
delete_files_and_chunks: to delete files and their chunks from the database.

Let's move on to the next command.

Implementing `rag docs remove`

rag docs remove <name>

This function will simply remove a documentation from the database, with all associated files and chunks.

export async function remove(name: string) {
  const documentation = await db.documentations.get(name)
  if (!documentation) return
  const files = await db.files.find({ documentation_id: documentation.id })
  await delete_files_and_chunks(files)
  await db.documentations.remove(name)
}

Here we reused some functions from the update command and added a new one:

db.documentations.remove: to remove a documentation from the database.

Organizing functions

Here is the list of functions we need to implement so far:

database functions

db.documentations.has
db.documentations.get
db.documentations.create
db.documentations.update
db.documentations.remove
db.files.find
db.chunks.remove
db.files.remove

files functions

hash_file
get_md_files

other functions

clone_repo
add_file_to_documentation
delete_files_and_chunks

I want to start with the database functions but these two functions bother me: add_file_to_documentation and delete_files_and_chunks. Why, because they hide other database functions inside. So let's start by them:

Implementing `add_file_to_documentation`

async function add_file_to_documentation(doc: db.Documentation, filename: string) {
  const chunks = await get_file_chunks(filename) // Oops, we need to pass the absolute path here
  await db.files.create({
    documentation_id: doc.id,
    path: filename,
    hash: await hash_file(filename) // Oops, we need to pass the absolute path here
  })
  // ...
}

Here is a problem, we need to pass the absolute path to the get_file_chunks and hash_file functions. But the filename is a relative path.

Why don't you just pass the absolute path directly?

Because we need to store the relative path in the files table on the database.

Hmm, so we need to pass the clone_path and relative path to the function, that way we can compute the absolute path?

Yes, that would be a valid solution, let's do it.

First we modify the code of add and update commands to pass the additional argument:

- await add_file_to_documentation(documentation, filename)
+ await add_file_to_documentation(documentation, clone_path, filename)

Ok, now let's continue with the add_file_to_documentation function:

export async function add_file_to_documentation(doc: db.Documentation, clone_path: string, filename: string) {
  const absolute_path = path.join(clone_path, filename)
  const chunks = await get_file_chunks(absolute_path)
  const file = await db.files.create({
    documentation_id: doc.id,
    path: filename,
    hash: await hash_file(absolute_path),
  })
  for (let index = 0; index < chunks.length; index++) {
    const { metadata, content } = chunks[index]
    const text = `${yaml.stringify(metadata)}\n---\n${content}`
    const embedding = await embed(text)
    await db.chunks.create({ file_id: file.id, index, metadata, content, embedding })
  }
}

This give us the following additional functions to implement:

get_file_chunks: to read a file and split it into chunks. it returns the content and metadata of each chunk.
db.files.create and db.chunks.create: to create a new file and its chunks in the database.
embed: to create the embedding vector of a string.

What is the db.Documentation type?

It's the type that represents a documentation in the database. We didn't define it yet, we will do with the database functions.

What is the purpose of embedding ${yaml.stringify(metadata)}\n---\n${content} instead of just embedding the content directly?

I am adding the metadata (that will contain things like the filename, the current section in the file, ...) to the embedded text to give more context in hope of improving the search results.

Again I am aware that this will be slow, I should probably use streams to do some work while reading files, I should also compute embeddings in batches, ... I will to those optimizations in the future.

Implementing `delete_files_and_chunks`

Here is the most basic implementation

async function delete_files_and_chunks(files: db.File[]) {
  for (const file of files) {
    await db.chunks.remove({ file_id: file.id })
    await db.files.remove({ id: file.id })
  }
}

With that we have the following remaining functions to implement:

database functions

db.documentations.has
db.documentations.get
db.documentations.create
db.documentations.update
db.documentations.remove
db.files.find
db.files.remove
db.files.create
db.chunks.create
db.chunks.remove

files functions

hash_file
get_md_files
get_file_chunks

other functions

clone_repo
embed

I will implement the database functions in the next article.

Summary

In this article, we wrote the outline code for the commands:

rag docs add
rag docs update
rag docs remove

And listed the internal functions we need to implement for those commands to work.

You can check the current code in Github: https://github.com/webNeat/rag

What's next

The next steps are:

Implement the missing functions
Implement the rag get command
Add tests
Measure and improve performance
Create CI/CD pipeline
Release the first version!

Feel free to comment if you have any suggestions or feedback. See you in the next article!

RAG - Creating the SQLite database and config file

Amine Ben hammou — Tue, 14 Jan 2025 08:55:52 +0000

This is the third article of a series in which I am building an open source RAG CLI tool. In the previous article we designed and started the implementation of the command line interface of the tool.

In this article, we will design the database to store the documentations and create a configuration file in the process.

The database schema

We already chose SQLite as a database, so let's define the tables we need.

The first table is documentations, it will store the docs information like name, repo url, subdir, branch, etc.

id int primary key
name text unique
repo_url text
subdir text
branch text
created_at timestamp
updated_at timestamp

When we run the rag docs add ..., a new row will be added to the documentations table, then we will fetch the markdown files from the given repo. So a files table makes sense.

id int primary key
documentation_id int
path text
hash text
created_at timestamp
updated_at timestamp

The path is the file path within the git repo. The hash is a hash of the file content.

Why do we need to store the file hash?

it will be useful when we do rag docs update, we can then fetch the new files and if we detect that the hash didn't change, we know that the file content didn't change, so we don't have to re-split it and update its chunks.

Hmm, then why don't we just store the old file content and compare with the new one directly?

The content of files will be stored as separate chunks, I think it's not worth it to also store them as a whole in the files table. This might just make the database larger for no useful reason.

The next table is chunks, it will store the chunks of the files.

id int primary key
file_id int
index int
metadata text
content text
embedding blob
created_at timestamp
updated_at timestamp

index is the index of the chunk in the file, this maybe useful if we want to construct the full file content from the chunks.
metadata will contain meta information about the chunk (I will define these metadata in details when we implement the rag docs add command).
embedding will store the embedding vector of the chunk.

Creating the database

Now that we have defined the database tables, it's time to write the code that will create the database when the user runs the first rag command. So as part of the initial checks that will be performed by all commands, is to check if the database exists and if not, create it.

So let's create a function init in src/init.ts to do that:

import * as db from './database'

export async function init() {
  if (!db.exists()) {
    await db.create()
  }
}

and use it in src/main.ts:

import { program } from 'commander'
import { init } from './init'

program.name('rag').version('0.0.1').description('Simple RAG system for developers')

// ...

init().then(() => program.parseAsync()).catch((err) => {
  console.error(err)
  process.exit(1)
})

Now let's create a src/db.ts file and implement the exists and create functions:

import os from 'os'
import path from 'path'
import { Database } from 'bun:sqlite'

const db_path = path.join(os.homedir(), '.rag/db.sqlite')

const db_schema = /* sql */ `
CREATE TABLE documentations (
  id INTEGER PRIMARY KEY,
  name TEXT UNIQUE,
  repo_url TEXT,
  subdir TEXT,
  branch TEXT,
  created_at INTEGER,
  updated_at INTEGER
);

CREATE TABLE files (
  id INTEGER PRIMARY KEY,
  documentation_id INTEGER,
  path TEXT,
  hash TEXT,
  created_at INTEGER,
  updated_at INTEGER
);

CREATE TABLE chunks (
  id INTEGER PRIMARY KEY,
  file_id INTEGER,
  index INTEGER,
  metadata TEXT,
  content TEXT,
  embedding BLOB,
  created_at INTEGER,
  updated_at INTEGER
);
`

export async function exists() {
  return Bun.file(db_path).exists()
}

export async function create() {
  await mkdir(path.dirname(db_path), { recursive: true })
  const db = new Database(db_path)
  db.transaction(() => {
    db.prepare(db_schema).run()
  })()
}

Hooold on, I have many questions about this code:
Why don't you use camelCase for the function names? isn't it the standard in Typescript?

Yes camelCase is the standard in Typescript, and I would use it if I was working within a team or on a code that will be called by other devs (a library). But here I am working alone and building a CLI, so I think I am free to use my preferred style. I find snake_case to be more readable then camelCase.

The comment in the line const db_schema = /* sql */ is weirdly placed, comments are normally written before the line or at the end of it, not in the middle.

I am using an extension that enables syntax highlighting within string templates, that comment specifies the language for the syntax.

I am not a fan of writing SQL code like that, it's error prone and hard to maintain, why don't you use a library like prisma or drizzle to handle this?

because I like to keep things simple and have control over my code. Every ORM comes with abstractions and some magic, so before I use it, I need to learn about how it works, what kind of queries it will generate, what are the assumptions and limitations ... I don't think it's worth it for this project, as I can write the SQL queries in less time.

But you only need to learn about the ORM once, and then you can use it for all your projects.

Yes, that's correct. if I wasn't in a hurry, I would spend more time learning it as an investment for future projects, or just out of curiosity. But I want to finish this tool as soon as possible and move on to the next project (I have a long waiting list that keeps growing ...).

The created_at and updated_at columns should be dates or timestamps, not integers, isn't it?

In other SQL databases, like MySQL and Postgres, yes that would be the case. But I just learned that SQLite only supports 5 datatypes: NULL, INTEGER, REAL, TEXT and BLOB.

From the SQLite datatypes documentation:

SQLite does not have a storage class set aside for storing dates and/or times. Instead, the built-in Date And Time Functions of SQLite are capable of storing dates and times as TEXT, REAL, or INTEGER values:

TEXT as ISO8601 strings ("YYYY-MM-DD HH:MM:SS.SSS").

REAL as Julian day numbers, the number of days since noon in Greenwich on November 24, 4714 B.C. according to the proleptic Gregorian calendar.

INTEGER as Unix Time, the number of seconds since 1970-01-01 00:00:00 UTC. Applications can choose to store dates and times in any of these formats and freely convert between formats using the built-in date and time functions.

So I chose to use integers for timestamps, and store the Unix timestamp in seconds.

That's weird, I have seen SQLite code that uses other types like DATETIME, VARCHAR(255) and FLOAT[100].

SQLite will accept any string as the column type (as long as the table is not in strict mode) and will automatically map it to one of the 5 datatypes above. For example:

VARCHAR(255) will be TEXT
FLOAT[100] will be BLOB
DATETIME will be INTEGER

I will not go deep into the conversion rules, but you can check details here: https://www.sqlite.org/datatype3.html

I see that you hard coded the database path, is there a way to make it configurable?

Yes, that's the next step.

Adding a configuration file

Before continuing with the database, let's add a configuration file that will store the database path and other settings we may add later.
We want to allow the user to change this file as they want, so instead of having a file in the source code (that will be compiled into a single executable), we will use a file in the user's home directory, let the path be ~/.rag/config.yaml (I chose YAML over JSON because I find it easier to write and read).

For now, a config file will look something like this:

database_path: ~/.rag/db.sqlite

Then we need some functions in our code to read and update that file, let's create a src/config.ts file:

import os from 'os'
import path from 'path'
import yaml from 'yaml'

export type Config = {
  database_path: string
}

const config_path = path.join(os.homedir(), '.rag/config.yaml')
const defaults: Config = {
  database_path: path.join(os.homedir(), '.rag/db.sqlite'),
}

export async function get() {
  if (!(await exists())) {
    await set(defaults)
    return defaults
  }
  return yaml.parse(await Bun.file(config_path).text())
}

export async function set(config: Config) {
  await Bun.write(config_path, yaml.stringify(config))
}

async function exists() {
  return Bun.file(config_path).exists()
}

This file exports the Config type, and the functions get and set to read and write the config.

I think calling the functions get_config and set_config is more readable than get and set in this case.

Let's talk about that. I tend to only add such prefixes to names (of variables, functions, classes, etc) when necessary. Most of the time, it's not.
In this case, we are already inside the config.ts file, so we don't need to specify it again in the function names.
You may say, "but what about when using the functions in other files?", then I will do the following:

import * as config from './config'

config.get() // to get the config
config.set(...) // to set the config

Hmm, interesting, so you use import * as just to avoid prefixing the function names?

Not only that, but also because I don't remember all the exported functions in the file/module, with this import I can type config. and let the IDE list all the functions for me.
I am not saying this approach is the best, it's just how I like to write/organize my code :P

Understood. Now I see another problem with that code; We don't validate the config after reading and before writing it. What happens if the user has a typo in the config file?

You are right, we should validate the config at runtime and show a proper error message if it's not valid.
I will add the validation now using zod and handle the proper error messages later (I will just print the Zod error directly to stderr for now).

import z from 'zod'

const Config = z.object({
  database_path: z.string(),
})
export type Config = z.infer<typeof Config>

export async function get() {
  // ...
  return Config.parse(yaml.parse(await Bun.file(config_path).text()))
}

export async function set(config: Config) {
  await Bun.write(config_path, yaml.stringify(Config.parse(config)))
}

Let's use the database path from the config file in the database functions:

import * as config from './config'

export async function exists() {
  const { database_path } = await config.get()
  return Bun.file(database_path).exists()
}

export async function create() {
  const { database_path } = await config.get()
  await mkdir(path.dirname(database_path), { recursive: true })
  const db = new Database(database_path)
  db.transaction(() => {
    db.prepare(db_schema).run()
  })()
}

Here I notice that we are calling config.get twice, and we are reading and parsing the yaml file each time. Let's read the config once and store it:

let config: Config | undefined

export async function get() {
  if (config === undefined) {
    if (!(await exists())) {
      await set(defaults)
      config = defaults
    } else {
      config = Config.parse(yaml.parse(await Bun.file(config_path).text()))
    }
  }
  return config
}

Summary

In this article,

we created the SQLite database
we created a configuration file

You can find the code in this repository: https://github.com/webNeat/rag

What's next

The next steps are:

Implement the commands logic
Add tests
Create CI/CD pipeline

Feel free to comment if you have any suggestions or feedback. See you in the next article!

RAG - Designing the CLI interface

Amine Ben hammou — Mon, 06 Jan 2025 09:57:54 +0000

This is the second article of a series in which I am building an open source RAG CLI tool. In the previous article we defined the goal of the tool and analyzed the steps to achieve it.

In this article, we will design the CLI interface and start writing some code.

Hold on, do I really need to read the previous article to be able to follow with this one?

Ideally yes, but here is the summary we achieved in the previous article:

We are building a CLI tool that stores documentations of different frameworks/libraries and allows to do semantic search and extract the relevant parts from them.

Requirements:

Git: will be used to clone the documentations repository
Ollama: will be used to generate embeddings

Assumptions / Limitations:

We are assuming that the documentations are available as markdown files on a Git repository

Database:
We choose to go with SQLite for now and add support for other databases in the future.

Designing the CLI interface

Brainstorming

Let's call our tool rag, the first commands that come to mind are:

rag setup: setup the requirements of the tool (git, ollama, the embeddings model, ...).
rag add: add documentations to the tool.
rag get: retrieve the relevant parts from documentations.

if I understand correctly, the setup command should be run right after the installation of the tool. What happens if the user doesn't run it and start by doing a rag add or rag get directly?

Good catch, my first idea would be to show an error message asking the user to run the setup command first. But now that I am thinking about it, if we can detect when some requirements are missing, then we can automatically install them, let the user know via a message (maybe on stderr to avoid polluting the output), and then continue with the requested command.

Pros: The commands just work out of the box, they automatically add missing requirements when needed. No need for a setup command.
Cons: All commands have to check requirements at startup, which can slow down the tool.

I think the resilience we gain by automatically handling requirements is worth the performance hit. A slower command is better than a command that doesn't work.

I agree with you on removing the setup command and checking requirements at the start of each command. But I would ask for user's permissions before installing any new software on their system.

You are right, we should ask for permissions before installing any new software.

Ok, now for the add command, what would be the arguments?

I was thinking of something like:

rag add <name> <repo_url> [--subdir <subdir>] [--branch <branch>]

<name>: the name of the framework/library
<repo_url>: the URL of the repository
--subdir <subdir>: a subdirectory of the repository where the documentation markdown files are stored
--branch <branch>: the branch of the repository

Looking good, but how do we handle different versions of the same framework/library?

Ah, good point. I feel like adding a --version flag would make the command complicated, especially because we should also point to the correct branch/tag to fetch the docs of the correct version.
A simpler way is to let the user handle that by adding the version to the name itself, something like

rag add tailwindcss:v2 https://github.com/tailwindlabs/tailwindcss --branch v2 --subdir src/pages/docs
rag add tailwindcss:v3.4 https://github.com/tailwindlabs/tailwindcss --branch v3.3 --subdir src/pages

I feel that this will be easier to handle while giving the user the ability to have docs of different versions of the same framework/library.

I am not convinced that this is the best approach, but let's go with it. Now what if the user already has a documentation in the database and try to add it again? will it overwrite the existing one?

Good question, I think we should show an error message saying that a documentation with the same name already exists.

Ok, but how would the user update a documentation that already exists?

We can add a new command to do that

rag update <name> [--repo_url <repo_url>] [--subdir <subdir>] [--branch <branch>]

This would update the existing documentation repo_url, subdir or branch if provided, then fetch and update the docs.

And we can also add a rag remove command to remove a documentation from the database when needed.

So far we have the following commands:

rag add <name> <repo_url> [--subdir <subdir>] [--branch <branch>]
rag update <name> [--repo_url <repo_url>] [--subdir <subdir>] [--branch <branch>]
rag remove <name>
rag get ...

Since the three commands add, update and remove handle docs, we can group them under a docs command:

rag docs add <name> <repo_url> [--subdir <subdir>] [--branch <branch>]
rag docs update <name> [--repo_url <repo_url>] [--subdir <subdir>] [--branch <branch>]
rag docs remove <name>

Good, now what about the get command? what are the arguments?

This is the main command of our tool, let's start with something like:

rag get <prompt> [--count <count>]

prompt: the prompt for which we want to retrieve the relevant parts
--count <count>: the number of relevant parts to retrieve

This would print the relevant parts to stdout.

What if the prompt contains multiple lines? wouldn't it make sense to read the prompt from stdin?

Hmm, yeah. Let's support both; if the argument exists we use it, otherwise we read the prompt from stdin.

I think it will also be useful to to have a json output option, so that we can call the command from within some code and easily parse the output.

Good idea, let's add a --json flag. With this flag, the output would be as follows:

[
  {
    "meta": {
      "collection": "tailwindcss:v3.4",
      "filename": "getting-started.md",
      "similarity": 0.8,
      ...
    },
    "content": "markdown content of the relevant part ..."
  },
  ...
]

Specifications

The rag tool will have the following subcommands:

# add new documentations
rag docs add <name> <repo_url> [--subdir <subdir>] [--branch <branch>]

# update existing documentations
rag docs update <name> [--repo_url <repo_url>] [--subdir <subdir>] [--branch <branch>]

# remove existing documentations
rag docs remove <name>

# get relevant parts from documentations
rag get <prompt> [--count <count>] [--json]

All commands should check for requirements at startup and ask for permissions before installing any new software on the user's system.

Implementing the CLI interface

Choosing the programming language

I think it's time to choose the language in which we will implement this tool, so that we can start to write some code. My constraints are:

I want to be able to ship the tool as a single executable file.
I want implement a working version as soon as possible.
The tool is not computationally intensive, and I don't need to handle many threads.

Given these constraints, I will go with Typescript and Bun for this project.

But you said you need to compile your code into a single binary, can Typescritpt do that?

Yes, Bun can produce a binary of your code: https://bun.sh/docs/bundler/executables

I thought Python was the preferred language for AI stuff, and it seems to fit your constraints.

Yes, Python would be a good option. I just chose Typescript because I am more familiar with it.

Creating the project

Let's start by creating an empty bun project:

bun init

After writing the project name rag and the entry file src/main.ts, I have the following directory structure:

node_modules/
src/
  main.ts
.gitignore
bun.lockb
package.json
tsconfig.json

I like to use Prettier to format my code, so

bun add -D prettier

and create a .prettierrc file:

{
  "printWidth": 155,
  "semi": false,
  "tabWidth": 2,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true
}

Implementing the CLI interface

I chose to use the commander package to implement the CLI interface. After installing it, I wrote the following code in src/main.ts:

import { program } from 'commander'

program.name('rag').version('0.0.1').description('Simple RAG system for developers')

const docs = program.command('docs').description('Manage documentations')

docs
  .command('add')
  .description('Add new documentation')
  .argument('<name>', 'Name of the documentation')
  .argument('<repo_url>', 'URL of the Git repository')
  .option('--subdir <subdir>', 'Subdirectory within the repository', '.')
  .option('--branch <branch>', 'Branch to use', 'main')
  .action((name, repo_url, options) => {
    console.log(`Adding documentation ${name} from ${repo_url} with options ${JSON.stringify(options)}`)
  })

docs
  .command('update')
  .description('Update existing documentation')
  .argument('<name>', 'Name of the documentation')
  .option('--repo_url <repo_url>', 'New repository URL')
  .option('--subdir <subdir>', 'New subdirectory within the repository')
  .option('--branch <branch>', 'New branch to use')
  .action((name, options) => {
    console.log(`Updating documentation ${name} with options ${JSON.stringify(options)}`)
  })

docs
  .command('remove')
  .description('Remove existing documentation')
  .argument('<name>', 'Name of the documentation')
  .action((name) => {
    console.log(`Removing documentation ${name}`)
  })

program
  .command('get')
  .description('Get relevant parts from documentations')
  .argument('<prompt>', 'Search prompt')
  .option('--count <count>', 'Number of relevant parts to retrieve', '5')
  .option('--json', 'Output results in JSON format')
  .action((prompt, options) => {
    console.log(`Getting relevant parts from documentations for prompt ${prompt} with options ${JSON.stringify(options)}`)
  })

program.parseAsync().catch((err) => {
  console.error(err)
  process.exit(1)
})

Now running bun src/main.ts shows the following output:

Usage: rag [options] [command]

Simple RAG system for developers

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  docs                    Manage documentations
  get [options] <prompt>  Get relevant parts from documentations
  help [command]          display help for command

And doing bun src/main.ts docs add tailwindcss https://github.com/tailwindlabs/tailwindcss shows the following output:

Adding documentation tailwindcss from https://github.com/tailwindlabs/tailwindcss with options {"branch":"main", "subdir":"."}

So I guess the CLI interface is working as expected.

No, you said that the prompt argument should be read from stdin if it doesn't exist. But it seems to be required right now.

You are right, if I do

bun src/main.ts get

I get the following error:

Missing required argument 'prompt'

To make the argument optional, we should use [prompt] instead of <prompt> in the argument definition. And now we can check when the argument is missing, and read it from stdin.

program
  .command('get')
  .argument('[prompt]', 'Search prompt')
  // ...
  .action(async (prompt, options) => {
    prompt = prompt || await Bun.stdin.text()
    console.log(`Getting relevant parts from documentations for prompt "${prompt}" with options ${JSON.stringify(options)}`)
  })

Which gives the following:

❯ bun src/main.ts get "arg prompt"
Getting relevant parts from documentations for prompt "arg prompt" with options {"count":"5"}

❯ echo "stdin prompt" | bun src/main.ts get             
Getting relevant parts from documentations for prompt "stdin prompt
" with options {"count":"5"}

Summary

In this article,

we designed the CLI interface and chose to have the commands add, update, remove and get.
we chose to implement the tool using Typescript and Bun.
we implemented the CLI interface using the commander package.

What's next

The next steps are:

Add the database
Implement the commands logic
Add tests
Create CI/CD pipeline

Feel free to comment if you have any suggestions or feedback. See you in the next article!

Building a CLI tool to improve Github Copilot

Amine Ben hammou — Wed, 04 Dec 2024 11:34:43 +0000

I am trying to use the new AI tools like Github Copilot and Aider to develop my applications faster. But I have one problem with them: they don't know how to use the recent versions of the frameworks/libraries I am using. This is normal because the new documentations where not part of their training data.

A trivial solution to this problem would be to just include the new documentation in the context. But this will be costly and make the response slow (and inaccurate sometimes). It's also not possible if I am solving a problem that invloves multiple tools (their docs would exceed the context size of the model).

I need a way to extract only the relevant parts of the documentations and add them to the prompt, I believe this is the idea behind RAG. So in this series of articles, I will share my journey of building a simple CLI tool that helps me store documentations and retrieve the relevant parts from them. I can then integrate this tool with AI assistants like Copilot and Aider, or just use it as an offline semantic search engine on documentations of tools I am using.

About this series

Why am I writing these articles?

I will publish the resulting tool as an open source project, and these articles will serve as a sort of documentation for that project. I believe this type of documentation is very interesting but rare. For example, I wish I could read the story of Linus when he was building the first version of Git, what was his thinking process? different problems he faced? what were the different designs/solutions he tried? etc. I think I would learn a lot from such story. So my goal here is to share my thinking process while I am building this tool, and the different problems I face and how I solve them. I hope you learn something from it, otherwise feel free to point out things I am doing wrong, I also want to learn.

The writing style

One easy way for me to explain my thinking process is to imagine that you are working with me on this project, and asking me questions like "why did you do this?", "did you consider this alternative?", etc. So whenever I think you may have a question, I will write it down as a quote and answer it, like the following:

Don't you think this will be distracting for the reader? I think it will be better to right in a normal way.

I know it might be distracting for some people, but others may like it, and I like it. So I will try it and see what people think in the comments.

Analyzing the problem

Let's start by defining what we are going to build and what tools we will be using.

Goal: Given a prompt, retrieve the relevant parts from multiple up-to-date documentations and add them to the context of the AI tool (e.g., Github Copilot).

To achieve this goal, I need to:

Download the up-to-date documentations
Do semantic search and extract the relevant parts
Add the relevant parts to the context of the AI tool

Let's analyze each one of these steps in more details.

1. Download the up-to-date documentations

For this step, I will assume that the documentations are available as markdown files on a Git repository. This assumption will make it easy to create the first version of the tool. We can add support for other types of docs and sources in the future. With this assumption, Downloading the documentations can be done by cloning the Git repository and extracting all markdown files from the docs directory.

2. Do semantic search and extract the relevant parts

What do you mean by semantic search?

From Wikipedia: Semantic search denotes search with meaning, as distinguished from lexical search where the search engine looks for literal matches of the query words or variants of them, without understanding the overall meaning of the query.

In short:

Lexical search: finding literal matches of the query words or variants of them.
Semantic search: understanding the meaning of the query and finding the relevant parts of the documentations.

I get the Lexical search, it's just looking for the parts that include some specific words. But I still don't get the semantic search, what do you mean by "understanding the meaning of the query"?

Here is a simplified explanation of how semantic search works:
Imagine that we can associate to each word a number that represents its meaning, and that words with similar meanings will have close numbers. Then if we want to test that two words have similar meanings, we can just compare their numbers. Now we can represent the meaning of a sentence (from the query or the documentation) as the list of numbers of each word in the sentence. Then to test if two sentences have similar meanings, we can just compute the distance between their list of numbers. The smaller the distance, the more similar the meanings.

Ok, but how do you come up with the number that represent the meaning of a word, wouldn't it change depending on the context?

Yes it would, the explanation above is just for you to get the idea. In practice, we use a library or an LLM to generate the list of numbers for a chunk of text, called embedding. The embedding would capture the overall meaning of the chunk, taking into account the contextual meaning of the words and the relationship between them. The AI models that are specialized in this are called embedding models. To generate embeddings, we can use an API like OpenAI's embedding models or run an open source emdedding model locally using a tool like Ollama.

I will go with the offline approach for this tool, because I am already familiar with Ollama and don't want the tool to require an API key from OpenAI or other service to work. I understand that this will add a new requirement to run the tool, but installing and running Ollama is easy and we can automate it if needed (I am thinking of a setup command that installs all requirements of the tool: Ollama, Git, etc).

Now that we have an idea of how to generate embeddings, here is how we can do semantic search:

Initialization:

Split the documentations markdown files into chunks.
Generate embeddings for all chunks.
Store each chunk and its embedding into a database.

Semantic search:

Generate an embedding for the prompt.
Query the database for chunks with similar embeddings.

So the next questions we should think about are:

How to split the documentations into chunks?
Which database we should use to store embeddings and query them?

Splitting the documentations into chunks

Input: The content of a markdown file

Output: A list of chunks

Constraints:

The number of tokens in a chunk should not exceed the limit of the embedding model.
We should not cut a heading or a sentence in the middle.
We should avoid cutting a paragraph, a code block, a table or a list in the middle as much as possible.
We should add metadata to each chunk to give context like the name of the framework/library, the version, the headings/titles that lead to the chunk, etc.

"The number of tokens in a chunk", what is a token?

A token is the unit of text used by LLMs, typically representing a word, part of a word, or character.

So we will need a way to count the number of tokens in a chunk, to ensure it does not exceed the limit, right? how?

Yes we will need to count the number of tokens in a chunk. The counting method depends on the embedding model we will choose. We will explore how to use the ollama API to count tokens during the implementation step.

Choosing a database

I would like the tool to be usable offline and easy to install, so the first database that comes to mind is SQLite. I can use an extension like sqlite-vec to enable vector search. Using SQLite makes it possible for users to backup their data or move it to another device by simply copying the database file. They can also but the database file on a server and share it between multiple devices/users.

What about performance? and accuracy of search?

I am not sure about that to be honest, I will have to do some benchmarks to compare SQLite against other databases to have a better idea. My thinking is to keep things simple and go with SQLite for the first version of the tool. We can always add support for other databases in the future.

3. Add the relevant parts to the context of the AI tool

Once we retrieve the relevant parts of documentations, we need a way to add them to the context of the AI tool. I will focus on two tools for now: Github Copilot and Aider. The same idea works for both of them: Write the chunks to a file and add that file to the context.

Github Copilot

We can configure Github Copilot to automatically include specific files in the chat context by adding the following to VSCode user settings:

{
  // ...
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": ".ai/docs.md" },
  ]
}

Then we can run our RAG tool and redirect the chunks to that file, then ask questions to Github Copilot.

Is there a way to let Github Copilot run our RAG tool on every prompt automatically? instead of having to run it manually?

This seems to be possible by building a Github Copilot extension, we can look into that in details once we finish the development of the tool.

Aider

We can configure Aider to automatically include specific files in the context using the read property of its config file

read:
  - .ai/docs.md

And there is a Feature request in the aider repository to enable integrating aider with external tools. So we could make it call our tool automatically and add the chunks to the context.

Summary

We are building a CLI tool that stores documentations of different frameworks/libraries and allows to do semantic search and extract the relevant parts from them.

Requirements:

Git: will be used to clone the documentations repository
Ollama: will be used to generate embeddings

Assumptions / Limitations:

We are assuming that the documentations are available as markdown files on a Git repository

database:
We choose to go with SQLite for now and add support for other databases in the future.

Next steps

In the next article, we will design the CLI interface and start the implementation of the tool.

How I Created an Extension to Automate VSCode With External Scripts

Amine Ben hammou — Tue, 23 Jan 2024 08:24:51 +0000

I wanted to use VSCode to manage my todo lists and ended up creating a framework for VSCode automation.

Problem 1: Open File

it all started when I wanted to use VSCode to handle my tasks, I use Todo+ which is great. But at some point, I wanted to split tasks into multiple files and I needed a way to navigate between them easily. So I would have something like:

project-42/
  index.todo
  add-features.todo
  add-tests.todo

the index.todo would contain

☐ create the project
☐ add-features.todo
☐ add-tests.todo
☐ make the PR

and the add-features.todo and add-tests.todo would contain some subtasks.

TDD guy: actually you should group each feature with its tests and write the tests then implement the feature ...

Response: Yes, I know, it's just an example to illustrate the separation of tasks into multiple files.

I wanted a way to open the add-features.todo and add-tests.todo simply by placing the caret inside them and hitting a keybinding.

Solution 1

I found an extension called Open file that does what I need.
After installing it, I could open the file under the cursor using alt+p (I could of course remap the command to any other keybinding).

Problem 2: Create file if missing then open it

if the file doesn't exist, I want the command to create it automatically.

The Open file doesn't support that so I need another way. Basically, when I press the keybinding, I want to execute the following commands:

create the file if missing
open the file

I found the Multi Command extension that can execute a sequence of commands. But I couldn't find a command or an extension that would create the relative file if missing without requiring any interaction/confirmation from me.

So, inspired by the JS ecosystem where everyone creates their own library/framework, I decided to create my own VSCode extension.

Problem 3: Create an extension to automate VSCode

The initial goal was to create a simple extension that creates the file under cursor then opens it. But I ended up creating a sort of framework that let's you automate VSCode using external scripts written with any language. Here is my journey step by step:

Step 1: Setup the project

npm install -g yo # install yoman globally
npm install -g generator-code # install the VSCode extensions generator globally

Then I run yo code and chose:

What type of extension do you want to create? New Extension (TypeScript)
What's the name of your extension? Create and open file
What's the identifier of your extension? create-and-open-file
What's the description of your extension? Create the relative file under the cursor if missing then opens it
Initialize a git repository? Yes
Bundle the source code with webpack? No
Which package manager to use? npm

Then I opened package.json of the generated project and modified the contributions section to be as follows:

{
  ...
  "contributes": {
    "commands": [
      {
        "command": "create-and-open-file.run",
        "title": "Create the relative file under the cursor if missing then opens it"
      }
    ]
  },
}

This tells VSCode that the extension adds the command create-and-open-file.run.

Next I opened the src/extension.ts and clears it to be as follows:

import * as vscode from "vscode"

export function activate(context: vscode.ExtensionContext) {
  // runs when the extension is activated
}

export function deactivate() {
  // runs when the extension is deactivated
}

Yes, basically an extension consists of two functions activate and deactivate. Most of the logic goes inside the activate function, which I will fill in the following steps.

Step 2: Implement the `create-and-open-file.run` command

Now all I needed to do is to implement the command in the src/extension.ts file as follows:

import * as vscode from "vscode"

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand("create-and-open-file.run", async () => {
    const editor = vscode.window.activeTextEditor // get current open tab
    if (!editor) return // if no current tab, do nothing
    const [line, position] = getLineAndPosition(editor) // get current line and position
    let filePath = extractFilePath(line, position) // extract the path under the cursor
    if (!filePath) return // if no path, do nothing
    filePath = normalizeRelativePath(editor, filePath)
    await createFileIfNotExists(filePath)
    await openFile(filePath)
  })
  context.subscriptions.push(disposable)
}

// implementation of functions `getLineAndPosition`, `extractFilePath`, `normalizeRelativePath`, `createFileIfNotExists` and `openFile` ...

That's it, now I could press F5 and try my extension. It's working!

Step 3: Design a more generic extension

So far, I had a working solution for my initial problem, but other ideas started appearing in my mind:

A command to list all pending tasks with certain tag.
A command to print the tree of task files with progress and remaining time for each file.
A command to show all tasks scheduled for today. ...

I wanted a way to be able to create these commands and any similar ones without having to create a whole new extension each time. After a bit of thinking, I found the following solution: Create an extension that can run any external script, give it the current context (the current file, the position/selection, ...) and execute the VSCode commands that are returned by the script. Let me explain the idea in more details:

The extension would add a command scripts.run to VSCode.
I can use that command to define keybindings like:

[
  // ...
  {
    "key": "alt+o",
    "command": "scripts.run",
    "args": {
      "script": "/path/to/my/executable/script"
    }
  }
]

When alt+o is pressed, the extension will run /path/to/my/executable/script and give it the following JSON in the standard input

{
  "file": "/absolute/path/to/current/file",
  "position": {
    "line": 10,
    "col": 5
  }
}

The script does anything (reads the file, creates new files, changes the content of some file, ...)
The script should output a JSON array of VSCode commands to the standard output. For example:

[
  { 
    "command": "type",
    "args": {
      "text": "Hello From the external script!"
    }
  }
]

The extension waits for the script to finish executing, parses the stdout and runs the returned commands.

So in this example, pressing alt+o would type Hello From the external script! in the current position.

Step 4: Implement the generic extension

I started by updating the name and description of the extension in package.json, then I renamed the create-and-open-file.run command as scripts.run. Then I updated the implementation as follows:

import * as vscode from 'vscode'
import * as commands from './commands'

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(vscode.commands.registerCommand('scripts.run', commands.run))
}

export function deactivate() {}

And created the file src/commands/run.ts that contains the implementation of the scripts.run command:

import * as vscode from 'vscode'
import { exec } from '../utils'

export async function run(args: {script: string}) {
  try {
    const stdout = await exec(args.script, JSON.stringify(getContext()))
    for (const command of JSON.parse(stdout)) {
      await runCommand(command)
    }
  } catch (e) {
    console.error(`Error: ${e}`)
  }
}

// implementation of `getContext` and `runCommand` ...

Step 5: Test the extension with a simple script

To test this implementation, I wrote the following Python script that should duplicate the current line (Why Python? for no reason, I could have chosen any other language):

import json
import sys

context = json.load(sys.stdin)
file = open(context['file'], 'r')
line = file.readlines()[context['position']['line'] - 1]
print(json.dumps([
  "cursorLineEnd",
  {'command': 'type', 'args': {'text': '\n' + line}}
]))

Then I defined the following keybinding

[
  // ...
  {
    "key": "alt+d",
    "command": "scripts.run",
    "args": {
      "script": "python3 /path/to/script.py"
    }
  }
]

I run the extension and pressed alt+d and the line is duplicated :D

Step 6: Handle selections and multi cursors

So far, I am passing a single cursor position to the script. What if there is a selection? I changed the context type to pass the start and the end of the selection (if there is no selection, then the start and the end will be equal):

type Context = {
  file: string
  selection: {
    start: {line: number, col: number},
    end: {line: number, col: number}
  }
}

Then to support the case of multiple selections:

type Context = {
  file: string
  selections: Array<{
    start: {line: number, col: number},
    end: {line: number, col: number}
  }>
}

Step 7: Solve the initial problem

At this point, I was happy with the result and wanted to use it to solve my initial problem: Open the file under cursor (creating it if missing). So I wrote the following script (I used Javascript this time):

async function main() {
  const { file, selections } = JSON.parse(await stdin())
  const position = selections[0].start // get the first cursor position
  const line = await readLine(file, position.line)
  let filename = extractPath(line, position.col)
  if (!filename) return '[]'
  await ensureFileExists(filename)
  return JSON.stringify(['seito-openfile.openFileFromText'])
}
main().then(console.log).catch(console.error)

// implementations of stdin, readLine, extractPath, ensureFileExists, ...

This worked well, but I noticed something: I was using the command seito-openfile.openFileFromText from the Open file extension, which has two cons:

For my script to work, I need that extension to be installed.
The seito-openfile.openFileFromText doesn't support specifying the file path programmatically (pass it as argument), it always uses the string under the cursor.

It was time for me to create some custom commands that I would need in my scripts and include them in the extension. Starting with scripts.files.open.

Step 8: Add the `scripts.files.open` command

I created a new file src/commands/files/open.ts

import * as vscode from 'vscode'

export async function open(args: {path: string}) {
  try {
    const document = await vscode.workspace.openTextDocument(args.path)
    await vscode.window.showTextDocument(document)
  } catch (e) {
    vscode.window.showErrorMessage(`Could not open file at '${args.path}': ${e}`)
  }
}

Then registered the command in src/extension.ts

import * as vscode from 'vscode'
import * as commands from './commands'

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(vscode.commands.registerCommand('scripts.run', commands.run))
  context.subscriptions.push(vscode.commands.registerCommand('scripts.files.open', commands.files.open))
}

export function deactivate() {}

Step 9: Publish the extension

Now that I had a working version of the extension, I decided to publish it so that I can test it in real life usage. So I created an account in the VSCode marketplace and published the extension, I had to rename it as Neat Scripts because scripts was taken.

What's next

I consider the currently published version an alpha version as I am still testing it and may change many things. Some next steps are:

Use the extension in real world and add common useful commands: show suggestions, add overlays, ...
Handle errors properly.
Add tests.
Write a good documentation with examples of usage in different languages.
Create a logo.
Think about a way to organize and share scripts

What do you think about this extension? feel free to open issues in the Github repo or reach out on Twitter. All feedback is welcome :)

Making the popup show faster

Amine Ben hammou — Mon, 06 Jun 2022 10:42:34 +0000

Hello 👋,

In the previous article, I shared how I started working on a small productivity tool called focus. The idea of the tool is simple:

I hit a keyboard shortcut anywhere on my computer.
A popup shows on the center of the screen containing a text input.
I type some idea/task I want to remember later, then I hit Enter.
The popup disappears.
All ideas I type are added to a text file. The path of that file is set by the environment variable FOCUS_TASKS_PATH.

Last time, I had a working version, but there is one problem: When I hit the keyboard shortcut, the popup takes about 2 seconds to open and render correctly. Let's make it "pop up" faster.

Why is it slow? it's just a text input right?
How to make it open faster ?
Adding the application to the system tray
Hiding the window from the frontend
Show the window with a global shortcut

Why is it slow? it's just a text input, right?

From my understanding of Tauri's process model, when I hit the shortcut, the following happens:

A core process is created. This is the process that runs the Rust code.
A webview process is created by the core process. This is the once running the frontend code.

You can think of a webview as a mini-browser that has everything needed to show a web page and handle interactions on it (parsing HTML, applying CSS, executing Javascript, ... ). Plus it can communicate with the core process to run Rust code.

This explains why it takes time the start it (like it takes time to open Chrome or VSCode).

How to make it open faster?

My idea is to open the app once and keep it running in the background so that when the shortcut is hit, we only show the window which should be faster than creating it from scratch. One way to do that is to add the app to the system tray (the section that has the small icons on the taskbar. You know the one that you close an app but still find its icon there telling you "I am still alive!").

Adding the application to the system tray

By following the documentation, first, we need to specify the icon of our app on the system tray using the tauri.conf.json file, let's use the already existing Tauri icon (I may need to design a custom icon for this application, but not a priority for now).

{
  "tauri": {
    // ...
    "systemTray": {
      "iconPath": "icons/32x32.png"
    }
  }
}

Next, I modified the dependencies section of the Cargo.toml file to include the feature gtk-tray which is needed on my Linux distribution.

tauri = { version = "1.0.0-rc.11", features = ["api-all", "gtk-tray", "system-tray"] }

Now we need to edit the main.rs file to create the system tray and specify the menu items attached to it

use tauri::*;

fn make_tray() -> SystemTray {     // <- a function that creates the system tray
  let menu = SystemTrayMenu::new()
    .add_item(CustomMenuItem::new("toggle".to_string(), "Hide"))
    .add_item(CustomMenuItem::new("quit".to_string(), "Quit"));
  return SystemTray::new().with_menu(menu);
}

fn main() {
  tauri::Builder::default()
    .system_tray(make_tray())  // <- adding the system tray to the application
    .invoke_handler(tauri::generate_handler![add_task])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

The make_tray function creates the system tray with a menu containing two items: Hide and Quit.

Initially, the application window is shown; I want to be able to hide it by clicking the Hide menu item. Then its text should become Show and clicking it should show the window again.
Clicking on the Quit menu item should close the application.

If I run the application now, I see the Tauri icon on the system tray. Clicking on it shows the menu with Hide and Quit items, but clicking them does nothing. To run some code when the items are clicked we should add an event handler using the on_system_tray_event method:

fn main() {
  tauri::Builder::default()
    .system_tray(make_tray())
    .on_system_tray_event(handle_tray_event)  // <- handling the system tray events
    .invoke_handler(tauri::generate_handler![add_task])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

Then we define the handle_tray_event function:

fn handle_tray_event(app: &AppHandle, event: SystemTrayEvent) {
  if let SystemTrayEvent::MenuItemClick { id, .. } = event {
    if id.as_str() == "quit" {
      process::exit(0);
    }
    if id.as_str() == "toggle" {
      let window = app.get_window("main").unwrap();
      let menu_item = app.tray_handle().get_item("toggle");
      if window.is_visible().unwrap() {
        window.hide();
        menu_item.set_title("Show");
      } else {
        window.show();
        window.center();
        menu_item.set_title("Hide");
      }
    }
  }
}

The result:

Hiding the window from the frontend

The next step is to hide the window when Enter is typed on the input instead of closing the application. To do so, let's update the App component's code:

//...
import { appWindow } from '@tauri-apps/api/window'

function App() {
  const [content, setContent] = React.useState('')
  const handleKeyDown = async (e: React.KeyboardEvent) => {
    if (e.key === 'Enter') {
      await invoke('add_task', { content })
      await appWindow.hide()
    }
  }
  // ...
}

Now when I type something and hit Enter, the window is hidden but there are two problems:

The menu item still shows Hide when I click the icon on the system tray.
When the window is shown again, the text I typed last time is still there.

Let's start by fixing the second problem which is easier. All we have to do is to set the content state to an empty string after invoking the add_task command.

function App() {
  const [content, setContent] = React.useState('')
  const handleKeyDown = async (e: React.KeyboardEvent) => {
    if (e.key === 'Enter') {
      await invoke('add_task', { content })
      setContent('')
      await appWindow.hide()
    }
  }
  // ...
}

The first problem is trickier. I didn't find a way to change the menu item text using the Javascript API. So it seems that I need to call Rust code to do that. Let's create a new command hide_window:

#[tauri::command]
fn hide_window(app: AppHandle) {
  let window = app.get_window("main").unwrap();
  let menu_item = app.tray_handle().get_item("toggle");
  window.hide();
  menu_item.set_title("Show");
}
//...
fn main() {
  tauri::Builder::default()
    .system_tray(make_tray())
    .on_system_tray_event(handle_tray_event)
    .invoke_handler(tauri::generate_handler![add_task, hide_window]) // <- added the command here
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

And call it from the frontend:

function App() {
  const [content, setContent] = React.useState('')
  const handleKeyDown = async (e: React.KeyboardEvent) => {
    if (e.key === 'Enter') {
      await invoke('add_task', { content })
      setContent('')
      await invoke('hide_window')
    }
  }
  //...
}

Note that the hide_window command takes an argument app of type AppHandle, but we don't pass any argument when calling it from Javascript. Tauri will inject that argument automatically based on its type.

Show the window with a global shortcut

So far, I was running a new instance of the application when typing the shortcut, now I want to just show the hidden window and not open a whole new instance. Tauri offers a way to register global shortcuts and run custom code when they are pressed.

Let's enable global shortcuts on tauri.conf.json

{
  "tauri": {
    "allowlist": {
      "globalShortcut": {
        "all": true
      }
    }
  },
  // ...
}

Then register the shortcut Alt+Enter by adding the following code to the main.tsx file:

import { register } from '@tauri-apps/api/globalShortcut'

register('Alt+Enter', () => {
  console.log('Alt+Enter pressed!')
})

Now the string Alt+Enter pressed! should be logged into the console every time I press Alt+Enter. But it doesn't work and I didn't know why ... until I found this open issue on the tao repository: https://github.com/tauri-apps/tao/issues/307

Tao is the Rust library Tauri uses to create and manage windows. And according to that issue, global shortcuts don't work properly on Linux, that's why it's not working for me!

So if I want to continue working on this application, I need to implement a workaround for shortcuts to work on Ubuntu. That's what I will be doing in the next blog post. See ya!

How I created the Focus app using React and Rust

Amine Ben hammou — Wed, 25 May 2022 00:56:28 +0000

Hello 👋,

In this article, I will describe the steps I went through to create a small desktop application to help me focus on my daily tasks.

The focus problem
The idea of the application
Setting up the project
Creating the UI
Calling Rust functions from the frontend
Customizing the tasks file path
Customizing the window
Closing the application after adding the task
Compiling, installing and using the application

The focus problem

One of my goals is to create the ultimate time management tool that will solve all my productivity issues, but let's start with one small problem for now.
When I am working on a task, I often get interrupted by other tasks that should be done (a new task is assigned to me, I remember something that I should do, ...), most of the time, the new task is not that urgent and can wait until I finish my current one. But it gets me distracted and sometimes I find myself prioritizing it over the current task only to not forget about it. Then resuming the original task becomes hard because I lost focus. To solve this problem I needed a way to quickly log interrupting tasks as they popup and forget about them until I finish my current task.

The idea of the application

I am working on something ... an interrupting idea/task appears.
I hit a custom shurtcut on my keyboard then a text input appears in the center of the screen.
I type a quick description of the interrupting idea/task, hit enter and the text input disapears.
I continue my work normally. ...
When I finish, I open a predefined file and find all the ideas/tasks I typed written inside it.

Setting up the project

What I am trying to build here is a desktop application, but I want to use web technologies (at least for the UI). The popular tool to do that is Electron, but I started recently learning Rust and Tauri seems like a good tool to try. So I will be using it with React for the frontend and Tailwind for styling.

I followed the instructions on Tauri's prerequisites page to setup Rust and Node on my system, then I run yarn create tauri-app to create the project. I named the project focus and chose the create-vite receipe for the UI and agreed to install @tauri-apps/api. Then chose the react-ts template of create-vite:

Tauri created the project and installed the dependencies. Let's take a look at the files structure:

src/
  main.tsx  <- entry point of JS/TS
  ... other UI files here
src-tauri/
  icons/           <- icons of different sizes
  src/
    main.rs        <- entry point for the application
  target/          <- the compiled and bundles files
  Cargo.toml       <- like package.json for Rust
  Cargo.lock       <- like yarn.lock
  tauri.conf.json  <- config file for Tauri
index.html         <- entry point of the UI
package.json
yarn.lock
tsconfig.json
vite.config.ts     <- config file for Vite

Now running the yarn tauri dev should start the app. This will take some time as Rust compiles the code for the first time, the following executions will be fast.

The final step of the setup was to add Tailwind to the project, I did that by following the official docs

Creating the UI

For the UI, all I need is a text input where I will type the task then hit Enter to save it. So I changed the App component code to the following:

function App() {
  return <input
    type="text"
    className="w-[800px] h-[80px] bg-[#222] text-2xl text-white px-6"
  />
}

Note that I am using Tailwind's arbitrary values syntax to have a dark gray 800px/80px input.

When I type some text in this input then hit Enter, I want that text to be appended to a file somewhere. Let's start by saving the text in a state and logging it when Enter is pressed:

function App() {
  const [content, setContent] = React.useState('')
  return (
    <input
      type="text"
      value={content}
      onChange={e => setContent(e.target.value)}
      onKeyDown={e => e.key === 'Enter' && console.log(content)}
      className="w-[800px] h-[80px] bg-[#222] text-2xl text-white px-6"
    />
  )
}

Calling Rust functions from the frontend

The next step is to write a Rust function that will receive the input content and append it to a file. After reading the Calling Rust from the frontend documentation page, I changed the src-tauri/src/main.rs to the following:

Warning: I am new to Rust, so I may be doing many things wrong in this code

#![cfg_attr(
  all(not(debug_assertions), target_os = "windows"),
  windows_subsystem = "windows"
)]

use std::fs::OpenOptions;
use std::io::prelude::*;

#[tauri::command]
fn add_task(content: String) {
  let mut file = OpenOptions::new()
    .create(true)
    .append(true)
    .open("../tasks.txt")
    .expect("Error while opening the tasks file");
  writeln!(file, "{}", content).expect("Error while writing in the tasks file");
}

fn main() {
  tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![add_task])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

Then I modified the App component to call that function when Enter is pressed:

function App() {
  const [content, setContent] = React.useState('')
  const handleKeyDown = async (e: React.KeyboardEvent) => {
    if (e.key === 'Enter') {
      await invoke('add_task', { content })
    }
  }
  return (
    <input
      type="text"
      value={content}
      onChange={e => setContent(e.target.value)}
      onKeyDown={handleKeyDown}
      className="w-[800px] h-[80px] bg-[#222] text-2xl text-white px-6"
    />
  )
}

Now when typing some text and hiting Enter, the entered text is added to the tasks.txt file.

Customizing the tasks file path

Note that this file is created in the root of the project while the path in the Rust code is ../tasks.txt, this is because the app is executed inside the src-tauri directory, so any relative path will be relative to that directory. It will be better to use an absolute path and let the user define it. The easiest way I could think of to define it is via an environment variable, let's call it FOCUS_TASKS_PATH.

So I added this variable to my .zshrc then updated the Rust code:

// ...
use std::env;

#[tauri::command]
fn add_task(content: String) {
  let path = env::var("FOCUS_TASKS_PATH") // read the env var
    .expect("The 'FOCUS_TASKS_PATH' env variable was not found!"); 
  let mut file = OpenOptions::new()
    .create(true)
    .append(true)
    .open(path)                           // <- use it here
    .expect("Error while opening the tasks file");
  writeln!(file, "{}", content).expect("Error while writing in the tasks file")
}

Customizing the window

The initial idea was to have a popup, something like Spotlight on macOS, but what we have now in a browser window! Luckily, Tauri allows us to tweak the window using the src-tauri/tauri.conf.json file. The initial window configuration was:

{
  "fullscreen": false,
  "height": 600,
  "resizable": true,
  "title": "Focus",
  "width": 800
}

I replaced it with

{
  "fullscreen": false,
  "width": 800,         // the width of the input
  "height": 80,         // the height of the input
  "title": "Focus",
  "resizable": false,
  "center": true,         // position it in the center of the screen
  "decorations": false    // remove the title bar
}

The result looks good :)

Closing the application after adding the task

Now I want the popup to disapear when I hit Enter, so let's add a process.exit() in our App component (This could also be added on the add_task Rust function).

import { process } from '@tauri-apps/api'

function App() {
  const [content, setContent] = React.useState('')
  const handleKeyDown = async (e: React.KeyboardEvent) => {
    if (e.key === 'Enter') {
      await invoke('add_task', { content })
      process.exit()
    }
  }
  //...
}

Now the popup is closed when Enter is pressed :)

Compiling, installing and using the application

I think we have the alpha version of the application ready now, let's build it

yarn tauri build

First the command failed with this message

Error You must change the bundle identifier in `tauri.conf.json > tauri > bundle > identifier`. The default value `com.tauri.dev` is not allowed as it must be unique across applications.

Setting the identifier to dev.webneat.focus solved the problem.

The compilation took a while then I had the following files generated (I am using Ubuntu):

src-tauri/target/release/bundle/
  deb/focus_0.1.0_amd64.deb
  appimage/focus_0.1.0_amd64.AppImage

Since the AppImage is easier to use (no installation needed), I just moved it to my bin directory and named it focus:

sudo mv src-tauri/target/release/bundle/appimage/focus_0.1.0_amd64.AppImage /usr/bin/focus

Now runing the command focus on the terminal opens the popup :D

On Ubuntu, I can setup a new custom shortcut on the Keyboard settings. Now when I hit that shortcut anywhere, The popup appears, I type what I have in mind and hit Enter then continue what I was doing 🎉

Check out the repository here https://github.com/webNeat/focus

DEV Community: Amine Ben hammou

How to Chat with Gemini 2.5 Pro from VSCode via AI Studio (Free and Unlimited)

Contents

1. Create a new chat file

2. Updating the chat file

3. Interacting with AI Studio in the browser

3.1. Attempt 1: Controlling the browser with Playwright

3.2. Attempt 2: Running a local server and injecting a JS snippet in the browser

3.2.1. Creating the HTTP server

3.2.2. Creating the client

3.3. Attempt 3: Creating a browser extension

3.3.1. Creating a separate server

3.3.2. Creating the browser extension

3.3.3. Socket communication between the service worker and the local server

3.3.4. Communication between the service worker and the content script

3.3.5. Putting it all together

4. Sending the message and getting the response in the browser

4.1. Writing the message in the textarea and sending it

4.2. Waiting for the response

4.3. Extracting the response as markdown and sending it to the service worker

5. Streaming the response to the file

Conclusion

RAG - Implementing the docs commands

Creating the commands files

Implementing the docs commands

Implementing rag docs add

Implementing rag docs update

Implementing rag docs remove

Organizing functions

Implementing add_file_to_documentation

Implementing delete_files_and_chunks

Summary

What's next

RAG - Creating the SQLite database and config file

The database schema

Creating the database

Adding a configuration file

Summary

What's next

RAG - Designing the CLI interface

Designing the CLI interface

Brainstorming

Specifications

Implementing the CLI interface

Choosing the programming language

Creating the project

Implementing the CLI interface

Summary

What's next

Building a CLI tool to improve Github Copilot

About this series

Why am I writing these articles?

The writing style

Analyzing the problem

1. Download the up-to-date documentations

2. Do semantic search and extract the relevant parts

Splitting the documentations into chunks

Choosing a database

3. Add the relevant parts to the context of the AI tool

Github Copilot

Aider

Summary

Next steps

How I Created an Extension to Automate VSCode With External Scripts

Problem 1: Open File

Solution 1

Problem 2: Create file if missing then open it

Problem 3: Create an extension to automate VSCode

Step 1: Setup the project

Step 2: Implement the create-and-open-file.run command

Step 3: Design a more generic extension

Step 4: Implement the generic extension

Step 5: Test the extension with a simple script

Step 6: Handle selections and multi cursors

Step 7: Solve the initial problem

Step 8: Add the scripts.files.open command

Step 9: Publish the extension

What's next

Making the popup show faster

Contents

Implementing `rag docs add`

Implementing `rag docs update`

Implementing `rag docs remove`

Implementing `add_file_to_documentation`

Implementing `delete_files_and_chunks`

Step 2: Implement the `create-and-open-file.run` command

Step 8: Add the `scripts.files.open` command