8000 GitHub - BlueCentre/code-agent: Code Agent CLI for interacting with LLMs and local environment
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

BlueCentre/code-agent

BranchesTags

Repository files navigation

Code Agent CLI

Quality Gate Status Coverage Maintainability Rating

Code Agent is a versatile Command-Line Interface (CLI) tool designed to enhance developer productivity by leveraging AI language models directly within the terminal.

It allows interaction with various AI providers (OpenAI, Groq, etc. via LiteLLM) and empowers the agent with capabilities to interact with the local environment, such as reading files, applying edits (with confirmation), and executing native commands (with confirmation and allowlisting).

DISCLAIMER: This repo and the tool itself is 99.95% built by LLM models such as Gemini 2.5 Pro and Claude 3.7 Sonnet! The remaining 0.05% goes to my prompts, designs, and gaurdrails to keep the agents in-check. 😜

(Work in progress)

Repository Structure

.
├── code_agent/       # Main package source code
│   ├── agent/        # Core agent logic and ADK agent implementations
│   ├── adk/          # Google ADK specific integration components
│   ├── cli/          # Command-Line Interface setup (Typer)
│   ├── config/       # Configuration management
│   ├── tools/        # Native tool implementations for the agent
│   └── verbosity/    # Verbosity and logging setup
├── sandbox/          # Experimentation and ADK testing environment
│   ├── agent_adk_runner/ # Simple ADK runner for testing
│   └── ...           # ADK test scripts
├── tests/            # Unit and integration tests
├── docs/             # Documentation files
│   ├── CONTRIBUTING.md
│   ├── architecture.md
│   ├── testing.md
│   └── ...           # Other guides and documentation
├── scripts/          # Utility scripts (testing, setup, etc.)
├── .githooks/        # Git hooks for quality checks
├── .github/          # GitHub Actions workflows
├── .venv/            # Virtual environment (typically excluded)
├── .gitignore        # Specifies intentionally untracked files
├── .pre-commit-config.yaml # Pre-commit hook configurations
├── .python-version   # Specifies Python version for pyenv
├── CHANGELOG.md      # Log of changes per version
├── LICENSE           # Project license file
├── Makefile          # Make commands for development tasks
├── pyproject.toml    # Project metadata, dependencies (PEP 621), and tool configs
├── README.md         # This file
├── sonar-project.properties # SonarCloud analysis configuration
├── uv.lock           # Pinned dependencies for UV
└── uv.toml           # UV project configuration (if used)

Key Directories

  • code_agent/: Contains the core source code for the CLI tool and agent logic.
  • sandbox/: Environment for experimentation and testing, particularly ADK features.
  • tests/: Test suite covering unit and integration tests.
  • docs/: Project documentation, guides, and architectural information.
  • scripts/: Utility scripts aiding development, testing, and CI/CD.
  • .github/: Contains GitHub Actions workflow definitions.
  • .githooks/: Local Git hooks to enforce standards before committing/pushing.

Documentation

  • README.md: Project overview, installation, and usage instructions
  • docs/: Detailed documentation about architecture, implementation, and specific features
  • docs/COVERAGE_VERIFICATION.md: Guide for verifying test coverage

Features

  • Multi-Provider Support:

    • Connect to different LLM providers using LiteLLM
    • Supports OpenAI, Google AI Studio, Groq, Anthropic, and more
    • Local model support via Ollama integration
    • Easily switch between providers with command-line flags

  • Versatile Interaction Modes:

    • Single-Shot Mode: Run individual prompts (code-agent run "...")
    • Interactive Chat: Engage in conversational sessions (code-agent chat)
    • Special chat commands: /help, /clear, /exit, /quit

  • Local Environment Integration (Agent Tools):

    • File System Access: Read file contents (read_file), list directory contents (list_dir).
    • Code Manipulation: Propose file edits with diff preview and confirmation (edit_file).
    • Command Execution: Run native terminal commands with safety checks and allowlisting (run_terminal_cmd).
    • Code Search: Semantic search across the codebase (codebase_search).
    • Text/Pattern Search: Find exact text or regex patterns within files (grep_search).
    • File Search: Locate files using fuzzy path matching (file_search).
    • Web Search: Access up-to-date online information (web_search).

  • Advanced Security Controls:

    • Path validation to prevent path traversal attacks
    • Workspace restrictions to limit file operations
    • Command validation and allowlisting to prevent dangerous operations
    • Optional auto-approval settings with clear security warnings

  • Rich Configuration System:

    • Hierarchical configuration (CLI > Environment > Config file)
    • Dynamic validation of settings
    • Provider-specific configuration options

  • User Experience Features:

    • Rich text output with Markdown rendering
    • Syntax highlighting for code
    • Clear error messages and troubleshooting information
    • Interactive confirmation prompts for system modifications

Quick Start

This section describes how to quickly install and run Code Agent as a user. For development or contribution, please see the Development & Contributing section.

Installation

  1. Install UV: Code Agent uses UV for package management. Install it first:

    # Install UV on macOS/Linux
curl -fsSL https://astral.sh/uv/install.sh | sh

    See the UV documentation for other installation methods.

  2. Install Code Agent:

    # Install using UV
uv pip install cli-code-agent

    (Assuming the package is published as cli-code-agent on PyPI)

    Alternative (Run directly from GitHub without installing):

    # Using uvx to run the latest version from the main branch
uvx --from git+https://github.com/BlueCentre/code-agent.git@main code-agent --help

Verify Installation

After installation, check that the command is available:

code-agent --help

If the code-agent command is not found, you may need to ensure the installation location's bin directory (where UV installs packages, often similar to pip's locations like ~/.local/bin) is included in your system's PATH environment variable.

First Run

Code Agent requires API keys for the LLM providers you want to use. Google AI Studio is the default provider.

  1. Set API Key: Get your AI Studio API key (starting with aip-) from Google AI Studio and set it as an environment variable:

    # Replace with your actual key
export AI_STUDIO_API_KEY=aip-your-key-here

    (See the Configuration section for setting keys for other providers or using the config file).

  2. Run a command:

    code-agent run "Hello! What can you help me with today?"

# Or start an interactive chat session
code-agent chat

Usage

Core Commands:

  • Run a single prompt:

    # Using default provider (AI Studio)
code-agent run "Explain the difference between a list and a tuple in Python."

# Specifying provider and model
code-agent --provider groq --model llama3-70b-8192 run "Write a Dockerfile for a simple Flask app."

  • Start interactive chat:

    # Using default provider
code-agent chat

# Specifying provider
code-agent --provider openai chat

    (Type quit or exit to leave the chat)

    Special Commands in Chat Mode:

    • /help - Show available commands
    • /clear - Clear the conversation history
    • /exit or /quit - Exit the chat session

  • Interact with local Ollama models:

    code-agent ollama list # List available local models
code-agent ollama chat llama3 "Ask a question..." # Chat with a specific model

    (See the Using Ollama section for details)

Configuration Management:

  • Show current config: 
    code-agent config show
  • View provider-specific configuration: 
    code-agent config aistudio  # Instructions for Google AI Studio
code-agent config openai    # Instructions for OpenAI
code-agent config groq      # Instructions for Groq
code-agent config anthropic # Instructions for Anthropic
code-agent config ollama    # Instructions for local Ollama models
  • List providers: 
    code-agent providers list
  • Reset to default configuration: 
    code-agent config reset

Other Options:

  • Show version: 
    code-agent --version
  • Show help: 
    code-agent --help
code-agent run --help
code-agent config --help

Configuration

Code Agent uses a hierarchical configuration system:

  1. CLI Flags: (e.g., --provider, --model) - Highest priority.
  2. Environment Variables: (e.g., OPENAI_API_KEY, GROQ_API_KEY) - Medium priority.
  3. Configuration File: (~/.config/code-agent/config.yaml) - Lowest priority.

A default configuration file is created automatically if it doesn't exist. You must edit ~/.config/code-agent/config.yaml or set environment variables to add your API keys for the desired providers.

Example ~/.config/code-agent/config.yaml:

# Default LLM provider and model
default_provider: "ai_studio"  # Options: "ai_studio", "openai", "groq", "anthropic", etc.
default_model: "gemini-1.5-flash"  # For AI Studio, use Gemini models

# API keys (Set via ENV VARS is recommended for security)
api_keys:
  ai_studio: null # Set via AI_STUDIO_API_KEY=aip-... environment variable
  openai: null    # Set via OPENAI_API_KEY=sk-... environment variable
  groq: null      # Set via GROQ_API_KEY=gsk-... environment variable
  # anthropic: null

# Agent behavior
auto_approve_edits: false # Set to true to skip confirmation for file edits (Use with caution!)
auto_approve_native_commands: false # Set to true to skip confirmation for commands (Use with extreme caution!)

# Allowed native commands (if non-empty, only these prefixes are allowed without auto-approve)
native_command_allowlist: []
  # - "git status"
  # - "ls -la"
  # - "echo"

# Custom rules/guidance for the agent
rules:
#  - "Always respond in pirate speak."
#  - "When writing Python code, always include type hints."

Using AI Studio Provider

Google AI Studio is now the default provider in Code Agent. To use it:

  1. Get an API Key:

    • Go to AI Studio
    • Create an account if you don't have one
    • Navigate to the API keys section and create a new key
    • Your API key will start with aip-

  2. Configure the Key:

    • Option 1: Set it as an environment variable: 
      export AI_STUDIO_API_KEY=aip-your-key-here
    • Option 2: Add it to your config file: 
      # In ~/.config/code-agent/config.yaml
api_keys:
  ai_studio: "aip-your-key-here"

  3. Specify Models:

    • AI Studio supports Gemini models
    • Default: gemini-1.5-flash (fast and efficient)
    • Other options: gemini-1.5-pro (more capable)
    • Specify a different model with the --model flag: 
      code-agent --model gemini-1.5-pro run "Write a Python function to detect palindromes"

  4. Switch Providers:

    • To use a different provider, use the --provider flag: 
      code-agent --provider openai --model gpt-4o run "Explain quantum computing"

Using Ollama for Local Models

Code Agent includes integration with Ollama to run open-source models locally on your machine:

  1. Install Ollama:

  2. Pull Models:

    • Pull the models you want to use: 
      ollama pull llama3
ollama pull codellama:13b

  3. Use the Ollama Commands:

    • List available models: 
      code-agent ollama list
    • Chat with a model: 
      code-agent ollama chat llama3:latest "Explain how to use async/await in JavaScript"
    • Add a system prompt: 
      code-agent ollama chat codellama:13b "Write a sorting algorithm" --system "You are a helpful coding assistant"

  4. Advantages of Local Models:

    • No API key required
    • Complete privacy - all data stays on your machine
    • No usage costs
    • Customizable with fine-tuning options

Development & Contributing

We welcome contributions to the Code Agent project! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.

Please see our Contributing Guide for detailed contribution guidelines, including coding standards, branch naming conventions, and the pull request process.

The project maintains high standards for code quality with:

  • Minimum 80% test coverage requirement
  • Comprehensive CI/CD pipeline using GitHub Actions
  • Conventional commit message format
  • Squash merging for a clean history

Setting Up Development Environment

  1. Prerequisites:

  2. Clone the repository:

    git clone https://github.com/BlueCentre/code-agent.git
cd code-agent

  3. Set up the environment:

    • Recommended (Quick Setup): Run the setup script. This creates a virtual environment, installs dependencies using UV, and installs Git hooks. 
      ./scripts/setup_dev_env.sh
    • Manual Setup (using UV): 
      # Create virtual environment
uv venv
# Install dependencies (including development dependencies)
uv sync --all-extras
# Install pre-commit hooks
uv run pre-commit install

Development Commands

The project includes a Makefile for common tasks, leveraging UV for execution. Activate your virtual environment (source .venv/bin/activate) before running these.

Command Description
make test Run all tests using pytest.
make test-unit Run only unit tests (@pytest.mark.unit).
make test-coverage Run tests with coverage report (fails if below 80%).
make test-report Run tests with coverage and open the HTML report.
make lint Check code style and formatting using Ruff.
make format Format code using Ruff.
make clean Remove build artifacts, caches, and coverage reports.
make code-agent-chat Start the interactive chat using the development version.
make swe-run-chat Run the Software Engineer ADK agent (console mode).
make swe-web-chat Run the Software Engineer ADK agent (web UI mode).

Git Workflow

This project follows a standardized Git workflow:

  • Branches: All changes are made in feature branches named <type>/<description> (e.g., feat/user-auth, fix/login-bug). Use the script: 
    ./scripts/create-branch.sh feat new-feature
  • Commits: Messages must follow the Conventional Commits format. 
    git commit -m "feat: add new feature"
  • Pushing: 
    git push -u origin feat/new-feature
  • See Git Development Documentation for complete details.

Git Hooks

This project uses A2A2 pre-commit to manage Git hooks and ensure code quality before commits. The hooks are defined in .pre-commit-config.yaml.

Hooks (like linting and formatting) are automatically run on git commit.

Installation: The hooks are installed automatically when you run the setup script (./scripts/setup_dev_env.sh). If you set up the environment manually, ensure you run:

uv run pre-commit install

This command only needs to be run once after cloning.

Testing

Tests are located in the tests/ directory (structured into unit, integration, and fixtures) and use the pytest framework. UV automatically uses the .venv virtual environment for the commands below.

Running Tests:

Use the Makefile targets:

# Run all tests
make test

# Run only unit tests
make test-unit

# Run tests with coverage (fails below 80%)
make test-coverage

# Run tests with coverage and open HTML report
make test-report

See Makefile or docs/testing.md for more details or specific test runs.

Development Workflow & Testing:

When developing:

  1. Make your changes in a feature branch.
  2. Test the development version directly using uv run or make: 
    # Example: Check version
uv run code-agent --version
# Example: Run a command
uv run code-agent run "Test prompt for my new feature"
# Example: Use a make target
make code-agent-chat
  3. Run the test suite to check for regressions: 
    make test
# Or run specific tests like 'make test-unit'
  4. Run the linter/formatter: 
    make lint
make format # If needed
  5. If adding new features, ensure you add corresponding tests to maintain coverage >= 80%.

Pull Request Process

When submitting a PR:

  1. The GitHub Actions CI pipeline automatically runs tests, linting, and checks coverage.
  2. Coverage reports are posted as comments on the PR.
  3. All checks must pass, and coverage must remain >= 80%.
  4. At least one reviewer must approve.
  5. Use "Squash and merge" for a clean main branch history.

GitHub Actions Workflows

This project uses GitHub Actions for automation:

  • Pull Request Checks (pr-workflow.yml, test-coverage.yml, test-e2e.yml): Automatically run on every pull request and push to the main branch. These workflows perform:
    • Linting and code formatting checks.
    • Unit and integration tests across Python versions.
    • End-to-end tests.
    • Code coverage calculation and reporting (including posting results to the PR).
  • Manual Trigger (test-coverage.yml): The test coverage workflow can also be manually triggered via the GitHub Actions tab (workflow_dispatch), useful for testing changes on demand.
  • Publish (publish.yml): Automatically publishes the package to PyPI when a new release tag is pushed.
  • Nightly (nightly.yml): Runs scheduled tasks (e.g., checks, updates). (Verify exact purpose if needed)

PR Validation & Monitoring

  • Validation: An optional feature provides immediate feedback on CI/CD checks after pushing changes. See PR Validation Documentation for setup.
  • Monitoring: Since Git lacks a reliable post-push hook, use a script to monitor PR status: 
    # Run after pushing to check CI status
./scripts/monitor-pr.sh
    See the PR Monitoring Script Documentation for details.

Running ADK Agents

This project includes agents compatible with the Google Agent Development Kit (ADK). Ensure you have installed the ADK (uv add google-adk or add to pyproject.toml and run uv sync).

Run agents using uv run adk run ... or uvx ... adk run ... within the activated environment.

Available agents and example commands:

  • Software Engineer Agent: 
    # Run scoped to agent dir
cd code_agent/agent/software_engineer && uvx --from git+https://github.com/google/adk-python.git@main adk run software_engineer
# Run web mode scoped to agent dir
cd code_agent/agent/software_engineer && uvx --from git+https://github.com/google/adk-python.git@main adk web
# Run scoped to top level
uvx --from git+https://github.com/google/adk-python.git@main adk run code_agent/agent/software_engineer/software_engineer
# Run web mode scoped to top level
uvx --from git+https://github.com/google/adk-python.git@main adk web code_agent/agent/software_engineer
  • Travel Concierge Agent: (Assuming similar structure) 
    cd code_agent/agent/travel-concierge && ./start_run.sh
  • Sandbox ADK Runner: 
    uv run adk run sandbox/agent_adk_runner

Upgrading

To upgrade Code Agent to the latest published version:

# Using UV
uv pip install --upgrade cli-code-agent

After upgrading, verify the new version:

code-agent --version

If you're using the Ollama integration, ensure your local Ollama installation is also up-to-date:

# Example: On macOS with Homebrew
brew upgrade ollama

# Or download the latest version from https://ollama.ai/download

About

Code Agent CLI for interacting with LLMs and local environment

ipv1337.dev

Topics

agent cli ai code

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

1 star

Watchers

2 watching

Forks

1 fork
Report repository

Releases

6 tags

Languages
0