streetrace 0.1.8

StreetRace is an agentic AI coding partner designed to help engineers leverage AI capabilities directly from the command line to create software.

StreetRace🚗💨

Today, StreetRace🚗💨 is a CLI-based assistant that can run agentic workflows, maintain your conversation histories, allowing full customization, and using any model supported by BerriAI/litellm, including self-hosted ollama models.

The goal is to enable:

1. Creating and using agents in your day-to-day SWE/SRE workflows.
2. Publishing and running your agents and other code to cloud envs.
3. Debugging, code generation, and diagnostics from CLI.

Here is a workflow that describes what StreetRace🚗💨 aims to be in v.1:

> streetrace
You: Create an agent that takes issues from our tracker API (documented in
..... @apis/my_issue_tracker.yaml), takes the latest issue with the highest priority,
..... and implements it. When complete and the implementation fully satisfies the
..... described requirements, publishes a PR on GitHub.
StreetRace: Working...
StreetRace: Your agent is created as "IssueFixer".
You: Deploy @IssueFixer and run it in a loop.
StreetRace: Working...
StreetRace: Deploying IssueFixer to yourk8shost.foo.bar...
StreetRace: IssueFixer is started and available at A2A endpoint issuefixer-001.foo.bar.
IssueFixer: There are 39 unresolved issues. Taking issue ISS007.
IssueFixer: Based on the issue description, I need to fix the app so it works.
IssueFixer: Looking for a solution...
IssueFixer: ...
IssueFixer: ISS007 is fixed, taking ISS042 now...
...

Installation and usage

Install from pip

$ pip install streetrace

Install from source

The code is managed by poetry. If it's not already installed, follow the poetry install guide.

$ git clone [e-mail]:krmrn42/street-race.git
$ cd street-race
$ poetry install
$ poetry run streetrace --model=$YOUR_FAVORITE_MODEL

Where $YOUR_FAVORITE_MODEL is the LiteLLM provider route (provider/model).

Environment Setup

Follow relevant LiteLLM guides to set up environment for a specific model. For example, for commercial providers, set your regular API key in the environment (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, etc), or OLLAMA_API_URL for local Ollama models.

Usage

streetrace is a CLI, and it can be installed as your dev dependency. It runs in the current directory, keeping all file reading and modifications in the current directory.

You can optionally supply a --path argument to provide a different working directory path.

$ streetrace --model=$YOUR_FAVORITE_MODEL
You: Type your prompt

Try in your environment

Currently, StreetRace includes one coding agent with a model of your choise. This agent is a capable software engineering agent that can work with your technology stack.

You can add more context to your prompts in two ways:

1. Using @-mentions, autocomplete will suggest local files that you can add to the prompt.
2. Any other project context can be added in a .streetrace folder:
   • SYSTEM.md is used as your system instruction.
   • Any other files under .streetrace are added as initial conversation messages.

Command Line Arguments

Session Management

StreetRace🚗💨 supports persistence of conversations through sessions. You can specify:

• --app-name - Application name for the session (defaults to the current working directory name)
• --user-id - User ID for the session (defaults to your GitHub username, Git username, or OS username)
• --session-id - Session ID to use or create (defaults to current timestamp)
• --list-sessions - List all available sessions for the current app and user

Examples:

# List all sessions for the current app and user
$ streetrace --list-sessions

# Create or continue a specific session
$ streetrace --session-id my-project-refactoring

# Work with a specific app name and user
$ streetrace --app-name my-project --user-id john.doe --session-id feature-x

If no session arguments are provided, StreetRace🚗💨 will:

1. Use the current working directory name as the app name
2. Use your detected user identity as the user ID
3. Create a new session with a timestamp-based ID

This allows you to maintain separate conversation contexts for different projects or tasks.

If you want to work with the same agent/context across multiple runs, use the same session ID.

Working with Files in Another Directory

The --path argument allows you to specify a different working directory for all file operations:

$ streetrace --path /path/to/your/project

This path will be used as the working directory (work_dir) for all tools that interact with the file system, including:

• list_directory
• read_file
• write_file
• find_in_files
• as a cwd in cli commands.

This feature makes it easier to work with files in another location without changing your current directory.

Interactive Mode

When run without --prompt, StreetRace🚗💨 enters interactive mode.

Autocompletion

• Type @ followed by characters to autocomplete file or directory paths relative to the working directory.
• Type / at the beginning of the line to autocomplete available internal commands.

Internal Commands

These commands can be typed directly into the prompt (with autocompletion support):

• /help: Display a list of all available commands with their descriptions.
• /exit: Exit the interactive session.
• /quit: Quit the interactive session.
• /history: Display the conversation history.
• /compact: Summarize conversation history to reduce token count.
• /reset: Reset the current session, clearing the conversation history.

For detailed information about the /compact command, see docs/commands/compact.md.

Non-interactive Mode

You can use the --prompt argument to run StreetRace🚗💨 in non-interactive mode:

$ streetrace --prompt "List all Python files in the current directory"

This will execute the prompt once and exit, which is useful for scripting or one-off commands.

CLI Command Safety

StreetRace🚗💨 includes an experimental safety mechanism for CLI command execution. Each command requested by the AI is analyzed and categorized into one of three safety levels:

• Safe: Commands from a pre-configured safe list with only relative paths
• Ambiguous: Commands not in the safe list but without obvious risks
• Risky: Commands with absolute paths, directory traversal attempts, or potentially dangerous operations

Risky commands are blocked by default to prevent unintended filesystem operations or system changes. This adds a layer of protection when working with AI-suggested commands.

The safety checker uses bashlex to parse and analyze commands and arguments, checking for:

• Command presence in a predefined safe list
• Use of absolute vs. relative paths
• Directory traversal attempts (using .. to move outside the working directory)

This helps ensure that StreetRace🚗💨 operates within the intended working directory and with known-safe commands.

Agent System

StreetRace🚗💨 includes a modular agent system that allows for specialized agents to be discovered and used.

Agent Discovery

The list_agents tool allows the assistant to discover available agents in the system. Agents are searched for in the following locations:

• ./agents/ (relative to the current working directory)
• ../../agents/ (relative to the src/streetrace/app.py)

Creating Custom Agents

StreetRace supports two ways to create custom agents:

Option 1: Using the StreetRaceAgent Interface (Recommended)

1. Create a directory for your agent in the ./agents/ folder (e.g., ./agents/my_agent/)

2. Create an agent.py file with a class that inherits from StreetRaceAgent and implements:

   • get_agent_card() - Returns metadata about the agent (name, description, capabilities)
   • get_required_tools() - Returns a list of tools the agent needs
   • create_agent() - Creates the actual agent instance with the provided model and tools

3. Add a README.md file with documentation for your agent

Example agent class:

from streetrace.agents.street_race_agent import StreetRaceAgent
from streetrace.agents.street_race_agent_card import StreetRaceAgentCard

class MyAgent(StreetRaceAgent):
    def get_agent_card(self) -> StreetRaceAgentCard:
        return StreetRaceAgentCard(
            name="My Agent",
            description="A specialized agent that does something useful",
            capabilities=["capability1", "capability2"],
        )

    async def get_required_tools(self) -> list[str]:
        return [
            "streetrace:fs_tool::read_file",
            "streetrace:fs_tool::write_file",
        ]

    async def create_agent(self, model_factory, tools) -> BaseAgent:
        model = model_factory.get_default_model()
        return Agent(
            name="My Agent",
            model=model,
            description="My specialized agent",
            instruction="You are a specialized agent that does X, Y, and Z...",
            tools=tools,
        )

Option 2: Legacy Approach (Basic Functions)

1. Create a directory for your agent in the ./agents/ folder (e.g., ./agents/my_agent/)

2. Create an agent.py file with these required functions:

   • get_agent_metadata() - Returns a dictionary with name and description keys
   • run_agent(input_text: str) - Implements the agent's functionality

3. Add a README.md file with documentation for your agent

Running Agents

The run_agent tool allows the primary assistant to execute specialized agents:

run_agent(
    agent_name="Hello World",
    input_text="What files are in this directory?",
    model_name="default"  # Optional, defaults to the default model
)

This enables a hierarchical agent system where the primary StreetRace assistant can delegate tasks to specialized agents.

Tool Configuration

Tools available to agents are defined in the ./tools/tools.yaml configuration file. This file specifies:

• Tool name and description
• Source type (e.g., 'local' for Python modules or 'mcp' for external services)
• Module and function name for local tools
• Whether the tool requires agent capabilities

The configuration makes it easy to add, modify, or disable tools without changing code.

Tool Discovery

The list_tools tool provides information about available tools that can be provided to agents. This helps the assistant understand what capabilities are available in the system.

The tool returns a list of available tools with:

• Tool name
• Description
• Whether the tool requires agent capabilities