codegraff

Python client for the codegraff agent. It drives the graff binary over its --json stdio protocol, with constants auto-generated from graff --schema.

Install

pip install codegraff

Note the package / module name mismatch: the PyPI package is codegraff, but the importable module is harness_sdk:

from harness_sdk import Harness

Prerequisite: the graff binary

The SDK spawns the graff binary as a subprocess, so it must be installed:

curl -fsSL https://github.com/justrach/codegraff/releases/latest/download/install.sh | sh

If graff isn't on your PATH, point at it explicitly with the binary argument (Harness(binary="./zig-out/bin/graff")).

Quick start

from harness_sdk import Harness

with Harness(yolo=True, model="gpt-5.5") as h:
    # one-shot: ask() returns just the final text
    print(h.ask("what is 2+2?"))

    # streamed: chat() iterates event dicts
    for ev in h.chat("read foo.txt"):
        print(ev["type"], ev)

# replace or extend the system prompt
with Harness(yolo=True, system_prompt="You are a code-review bot. Only report bugs.") as bot:
    print(bot.ask("review main.py"))

Harness accepts yolo, model, cwd, system_prompt, binary, and more. model may be a model name or a provider id (e.g. "codex", "moonshot"). Also exported: MODELS and PROVIDERS.

Events

chat() yields event dicts, each with a type:

  • text — assistant text delta
  • tool_call — the agent invoked a tool (name, input)
  • tool_result — a tool returned
  • ask_user — the agent needs input; answer it with the call_id
  • turn — turn finished; carries the final text, context_tokens, and cost_usd
  • error — something went wrong

Remote (no local binary)

Edge / serverless runtimes can't spawn a subprocess. Run graff serve somewhere and drive it over HTTP (stdlib urllib only):

from harness_sdk import RemoteHarness

with RemoteHarness("http://127.0.0.1:8787", token="...", yolo=True) as h:
    print(h.ask("what is 2+2?"))

Links

License

BSD-3-Clause

Project links

Data verified by PyPI on Jun 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for justrach from gravatar.com justrach

GitHub Statistics

Data verified by PyPI on Jun 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD-3-Clause

Requires

Python >=3.8

Tags

codegraff graff agent llm harness sdk

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codegraff-0.3.1.tar.gz (9.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

codegraff-0.3.1-py3-none-any.whl (9.1 kB view details)

Uploaded Python 3

File details

Details for the file codegraff-0.3.1.tar.gz.

File metadata

  • Download URL: codegraff-0.3.1.tar.gz
  • Upload date:
  • Size: 9.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codegraff-0.3.1.tar.gz
Algorithm Hash digest
SHA256 282f13ca232dae68f2a678c7170268cd2a0611c3791ff8e25ff3b7affbf7b3b2
MD5 c856209dfb46ea57ffe1ecd5bf1229d1
BLAKE2b-256 aab2d8b9be6b42f14132a05b59a2c71793817b36732d44788b22328648e4e730

See more details on using hashes here.

Provenance

The following attestation bundles were made for codegraff-0.3.1.tar.gz:

Publisher: sdk.yml on justrach/codegraff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codegraff-0.3.1-py3-none-any.whl.

File metadata

  • Download URL: codegraff-0.3.1-py3-none-any.whl
  • Upload date:
  • Size: 9.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for codegraff-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 20d48e2eac3999621b232c56ddc8904214aa39ee7a1841ec4a7ac432a774e605
MD5 9450e16f4feafed134e097796f6f60e5
BLAKE2b-256 cb296b5bc8e5daa45ca2a3c827bcf1c9b9a342fc5b5e75d64082d3c92ef98f9e

See more details on using hashes here.

Provenance

The following attestation bundles were made for codegraff-0.3.1-py3-none-any.whl:

Publisher: sdk.yml on justrach/codegraff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page