DEV Community

Sanchit
Sanchit

Posted on

Agent Harness Devlog #001

#ai #claude #agents #tutorial

I'm looking into building an agent harness, this is the first in series for devlog posts and are non-ai, human generated.

The Init

It starts with a working directory, provided by the current process or a custom path.

/app/codeworksh/codework
Enter fullscreen mode Exit fullscreen mode

This seemingly simple filesystem path has a lot going for it, e.g this could be a git repo, nested module within a git repo, or no repo at all, etc.

The idea here is to start somewhere at a filesystem. The mental model of a filesystem is a view to some data on computer partitioned by the filesystem tree, you can walk this tree (will explore this later). This view should be pluggable allowing for custom implementations like VFS, a virtual filesystem whose underlying implementation can be real OS filesystem, in-memory, sqlite, or etc, providing a common interface irrespective of the underlying implementation. see vfs

Location

The location data model represents the instance of working location aka directory example

interface Location {
    directory: string // directory path example os.cwd()
}
Enter fullscreen mode Exit fullscreen mode

The directory path within a machine is always unique, no two paths exists within the same machine, the underlying OS filesystem makes those guarantees, with that knowledge we can also use the directory within a machine as unique key.

With this directory as the unique key, allows us to attach some runtime metadata to the location, allowing us to view the location as a world domain called Project.

Project

A project is a real world domain mental model representing metadata + location. The metadata can be:

  • a git repository
  • named directory meaning
  • some other identification
  • source files or some binary data, etc.

The most common way to think about a location with metadata is a git repository. Take an example

/app/codeworksh/codework
    .git // git@github.com/codeworksh/codework
    package.json
    ...
Enter fullscreen mode Exit fullscreen mode

Git gives us the common location metadata like name of repository, unique identifier (repo URL), etc. With this we can build the domain model of a Project. Will be exploring more about Git later, there are lot of functionality for it.

Note: Git is just one example here, we can also have git like/specific protocol e.g Cloudflare Artifacts, svn, etc

Example

// git@github.com/codeworksh/codework

interface Project {
    id: string;
    name: string; // codework
    vcs: string; // git
    directories: ProjectDirectory[]
}

interface ProjectDirectory {
    id: string;
    directory: string;
    type: 'main' | 'root' | 'gitworktree'
    sandboxEnvID: string;
}
Enter fullscreen mode Exit fullscreen mode

Project:

  • id - unique identifier generated via hash of git URL or some UUID see UUID7
  • name - generated via git repo name
  • vcs - defaults to git string

Project Directory:

  • id - unique identifier
  • directory - absolute path in the filesystem
  • type - type of directory
    • main - The primary, first-seen clone of the repository.
    • root - Any other independent clone of the exact same repository on your disk.
    • gitworktree - A dynamically created linked copy spun off from one of the roots.

For a non git project a Project can be more simpler with static attributes
Example

interface Project {
    id: 'local';
    name: string; // directory name
    vcs: 'unknown';
    directories: ProjectDirectory[]
}
Enter fullscreen mode Exit fullscreen mode

For non-git directory there is no single best way to globally identify the sources or at least cheaply. Versioned control systems like git allows you to have multiple copies on your machine with same .git it's easy to track hence having directories makes sense, all directories pointing to same project.

Next will be exploring more on this location, building the project domain, and also storing in sqlite DB.

If you like what you read checkout the repo: https://github.com/codeworksh/codework

PS: Would love some stars, keeps me motivated.

Top comments (0)