Tutorial 01

Getting Started — Your First AI Coding Agent

In this tutorial you will install Harness, configure your first provider, and run an AI coding agent against a real codebase in under ten minutes. No prior agent experience required.

Introduction

Harness is an open-source coding agent that runs entirely from your terminal. Unlike GUI-based tools, every behaviour is scriptable, auditable, and embeddable in your existing CI/CD pipelines. This template demonstrates every reusable component available in the tutorial series.

The inline code component renders like this: harness run --task "fix all linting errors". Use it for short commands or identifiers inside body text.

Prerequisites

Python 3.11 or later
uv package manager installed
An API key for Anthropic, OpenAI, Google, or a local Ollama instance

Code Blocks

Code blocks support a language badge, an optional filename, and a copy-to-clipboard button.

Bash

uv tool install harness-agent
harness --version

Python agent.py

import asyncio
import harness

async def main():
    async for message in harness.run(
        "Refactor utils.py to use type hints",
        provider="anthropic",
        model="claude-sonnet-4-20250514",
        permission_mode="accept_edits",
    ):
        match message:
            case harness.TextMessage(text=t, is_partial=False):
                print(t)
            case harness.ToolUse(name=name):
                print(f"  Tool: {name}")
            case harness.Result() as r:
                print(f"Done: {r.turns} turns, ${r.total_cost:.4f}")

asyncio.run(main())

TOML ~/.harness/config.toml

[provider]
name    = "anthropic"
model   = "claude-opus-4-6"
api_key = "sk-ant-..."

[budget]
max_tokens = 50000
max_cost   = 1.00   # USD

[permissions]
mode = "accept_edits"

Provider Tabs

The tab component lets readers select their AI provider. Each tab panel contains provider-specific instructions.

Tab Usage

Set your Anthropic API key as an environment variable:

Bash

export ANTHROPIC_API_KEY="sk-ant-..."
harness init --provider anthropic --model claude-opus-4-6

Set your OpenAI API key as an environment variable:

Bash

export OPENAI_API_KEY="sk-..."
harness init --provider openai --model gpt-4o

Set your Google AI API key as an environment variable:

Bash

export GOOGLE_API_KEY="AIza..."
harness init --provider google --model gemini-2.0-flash

Run Ollama locally, then point Harness at your local endpoint. No API key required.

Bash

ollama pull llama3.3
harness init --provider ollama --model llama3.3 --base-url http://localhost:11434

Callout Boxes

Info

Harness stores its configuration at ~/.harness/config.toml with permissions set to 0o600 so only your user account can read it.

Warning

Never commit your config.toml file to version control. Add it to your .gitignore before running git init.

Success

If you see Agent initialised in the terminal output, Harness has successfully connected to your provider and is ready to accept tasks.

Error

A 401 Unauthorized response means your API key is invalid or has expired. Regenerate the key in your provider's dashboard and update config.toml.

Try It

Open your terminal right now and run harness run --task "list all TODO comments in this repo" inside any project. The agent will scan your code and produce a structured report in seconds.

Collapsible Sections

Use collapsibles for optional deep-dives, advanced configuration, or troubleshooting details that would otherwise break reading flow.

Harness loads its system prompt from ~/.harness/system_prompt.md if the file exists. You can override any default instruction by adding your own directives to this file.

The agent uses an action-oriented prompt by design: it should never ask clarifying questions when running in bypass mode. To enforce stricter guardrails, use mode = "supervised" in your config instead.

If Harness times out when connecting to your provider, check your network proxy settings. Set HTTPS_PROXY in your environment and restart the agent.

You can also increase the default request timeout by adding timeout = 120 (seconds) to the [provider] section of your config.

Step Indicators

Use numbered steps for installation flows, setup wizards, or any process that must be followed in sequence.

Install Harness via uv

The recommended installation method is via the uv tool manager, which places the harness binary in ~/.local/bin/.

Bash

uv tool install harness-agent

Initialise your configuration

Run the interactive setup wizard to create ~/.harness/config.toml with your chosen provider and model.

Bash

harness init

Run your first task

Navigate to any project directory and issue a task in plain English. Harness will plan, execute, and summarise the changes it made.

Bash

cd ~/my-project
harness run --task "Add type hints to all functions in src/"

Competitor Comparison

See how Harness stacks up against other popular AI coding agents across the enterprise features that matter most.

What competitors can't do

14 enterprise features exclusive to Harness or unavailable in competing tools

Feature	Harness	Claude Code	Cursor	Aider	OpenHands	SWE-Agent
Multi-provider (5+)	✓	✗	✗	✓	✓	✗
Full async SDK	✓	✗	✗	✗	✓	✗
4-mode permissions	✓	✗	✗	✗	✗	✗
Token/cost budgets	✓	✗	✗	✗	✗	✗
Policy-as-code	✓	✗	✗	✗	✗	✗
Audit hash chain	✓	✗	✗	✗	✗	✗
Dual sandbox modes	✓	✗	✗	✗	✓	✓
Sub-agent parallelism	✓	✓	✗	✗	✗	✗
Native CI/CD	✓	✗	✗	✗	✗	✗
Model router + fallback	✓	✗	✗	✗	✗	✗
PII scanning	✓	✗	✗	✗	✗	✗
OpenTelemetry	✓	✗	✗	✗	✗	✗
Hooks system	✓	✓	✗	✗	✗	✗
REPL with slash cmds	✓	✓	✗	✗	✗	✗