turls

Install AI agent tools into your codebase. Think of it like shadcn but for AI agents.

You are building an AI agent and you need a file search tool, a memory store, or a vector database. Instead of writing everything from scratch or hunting through npm, you just run a command and the code lands in your project. You own it. You can modify it. No black boxes.

Getting Started

npm install -g turls

Then in your project:

turls init
turls add file-search
turls add memory-store

That is it. The tool code is now in your project, ready to use.

Architecture

turls follows the shadcn model: tools are small, composable, and live in your project. You can modify them freely.

Primitives vs Composites

Tools come in two flavors:

| Type | Description | Example | |------|-------------|---------| | Primitive | Small, focused, zero turls dependencies | html-to-md, sqlite-kv, cosine-sim | | Composite | Built by composing primitives | web-scrape = browser-launcher + html-to-md |

When you install a composite, its dependencies are automatically installed:

turls add web-scrape
# Automatically installs browser-launcher and html-to-md

Tool Dependency Graph

web-scrape
├── browser-launcher (primitive)
└── html-to-md (primitive)

memory-store
└── sqlite-kv (primitive)

vector-search
├── cosine-sim (primitive)
└── sqlite-kv (primitive)

file-search
├── glob-matcher (primitive)
└── grep-matcher (primitive)

How Composition Works

When you run turls add web-scrape, the installer:

1. Fetches web-scrape and its dependencies (browser-launcher, html-to-md)
2. Copies all files into your project
3. Rewrites imports from @turls/browser-launcher to relative paths
4. Installs npm/pip dependencies

After install, you own everything:

src/tools/
├── web-scrape/
│   └── index.ts       # Your code, modifiable
├── browser-launcher/
│   └── index.ts       # Your code, modifiable
└── html-to-md/
    └── index.ts       # Your code, modifiable

Customizing Tools

Since you own the code, you can:

• Modify behavior: Edit the source directly
• Add features: Extend functions with your own logic
• Remove unneeded parts: Strip out what you don't use
• Share improvements: Submit PRs back to the registry

What is Inside

Primitives

| Tool | What It Does | Languages | |------|--------------|-----------| | html-to-md | Convert HTML to clean Markdown | TypeScript, Python | | browser-launcher | Launch headless browsers | TypeScript, Python | | sqlite-kv | Key-value store backed by SQLite | TypeScript, Python | | cosine-sim | Compute cosine similarity between vectors | TypeScript, Python | | glob-matcher | Match files using glob patterns | TypeScript, Python | | grep-matcher | Search file contents with regex | TypeScript, Python |

Composites

| Tool | What It Does | Composes | |------|--------------|----------| | web-scrape | Scrape URLs, return clean Markdown | browser-launcher + html-to-md | | memory-store | Persistent memory with sessions & TTL | sqlite-kv | | vector-search | Vector similarity search with persistence | cosine-sim + sqlite-kv | | file-search | Search files by name and content | glob-matcher + grep-matcher |

Commands

turls init [--path <dir>]  # Set up turls (custom install path)
turls add <tool>           # Install a tool (resolves dependencies)
turls remove <tool>        # Remove a tool
turls update <tool>        # Update to latest version
turls list                 # See what you have installed
turls search [query]       # Browse available tools
turls sources              # Manage registry sources

Init with Custom Path

# Default: installs to src/tools/
turls init

# Custom path
turls init --path lib/agent-tools
turls init --path tools/ai

Adding Tools

# Add a primitive (no dependencies)
turls add html-to-md

# Add a composite (installs dependencies automatically)
turls add web-scrape

# Specify language
turls add memory-store --lang python

# Skip dependency installation
turls add memory-store --no-deps

# Skip import rewriting
turls add web-scrape --no-rewrite

Generating Code for Unsupported Languages

If a tool doesn't support your language yet, use --generate to create it via AI:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=sk-or-...

# Generate a Go implementation from the existing TypeScript code
turls add html-to-md --lang go --generate

# Or pass the key directly
turls add cosine-sim --lang rust --generate --api-key sk-or-...

The AI reads the existing implementation as reference and translates it to your target language.

Each Tool is Standalone

Every tool in the registry has:

registry/tools/{tool-name}/
├── manifest.json           # Tool metadata + dependencies
├── typescript/
│   ├── index.ts            # Source code
│   ├── package.json        # For isolated testing
│   ├── tsconfig.json       # TypeScript config
│   └── __tests__/
│       └── index.test.ts   # Tests
└── python/
    ├── index.py            # Source code
    ├── pyproject.toml      # For isolated testing
    └── tests/
        └── test_{name}.py  # Tests

You can test tools in isolation:

# TypeScript
cd registry/tools/html-to-md/typescript
npm install && npm test

# Python
cd registry/tools/html-to-md/python
uv pip install -e ".[dev]"
pytest

Adding Your Own Tools

The registry lives at github.com/OVECJOE/turls/registry/. To add a tool:

1. Create a folder under registry/tools/your-tool-name/
2. Add a manifest.json with your tool details
3. Add TypeScript and/or Python implementations
4. Add tests
5. Send a pull request

Manifest Format

{
  "name": "my-tool",
  "description": "What it does",
  "languages": ["typescript", "python"],
  "files": {
    "typescript": ["index.ts"],
    "python": ["index.py"]
  },
  "dependencies": {
    "typescript": ["some-npm-package"],
    "python": ["some-pip-package"]
  },
  "toolDependencies": ["other-turls-tool"],
  "version": "1.0.0",
  "author": "you"
}

Custom Registries

You can point to your own registry:

turls sources --add my-tools https://github.com/you/your-registry
turls add your-tool --source my-tools

For AI Engineers

If you are building agents, you know the struggle. Every agent needs different tools and you end up wiring the same things over and over. turls gives you a curated set of battle-tested tools that you can drop into any project.

The registry is community driven. If something is missing, build it and share.

Development

git clone https://github.com/OVECJOE/turls.git
cd turls
npm install
npm test

Running Tests

# Run all turls CLI tests
npm test

# Run individual tool tests
cd registry/tools/html-to-md/typescript && npm test
cd registry/tools/html-to-md/python && pytest

License

MIT