githosted 0.1.0

Python SDK for githosted — git-backed file storage for AI agents

githosted

Python SDK for githosted — read, write, and diff files in versioned Git repos without shelling out.

githosted exposes a small, typed surface for the operations you actually do against a repo: read a file, commit a change, list history, diff two refs. Real Git underneath; you're not talking to a custom blob store.

Install

pip install githosted

Requires Python 3.10+.

Quick start

from githosted import Client

repo = Client(token="gw_…").repo("my-agent")

# Write a file (creates a commit).
repo.write_file("output.json", b'{"status": "ok"}', message="Run #42")

# Read it back.
result = repo.read_file("output.json")
print(result.content.decode())

# Walk recent history.
for commit in repo.log(limit=5):
    print(commit.hash[:7], commit.subject)

# Diff between two refs.
delta = repo.diff("HEAD~1", "HEAD")
print(delta.patch)

Authentication

Tokens are scoped to a workspace. Mint one at app.githosted.dev → Tokens, then pass it to Client(token=…).

Token prefix	Scope
gw_…	Read + write
gr_…	Read-only

For local development, set GITHOSTED_TOKEN and use Client.from_env().

Errors

The SDK raises typed exceptions you can match on:

from githosted import (
    Client,
    NotFoundError,
    RepoBusyError,
    StaleHeadError,
)

try:
    repo.read_file("missing.txt")
except NotFoundError:
    ...

RepoBusyError and StaleHeadError are retryable — with_retry() is included for the common backoff loop.

Documentation

• Quickstart
• Python SDK reference
• HTTP API

License

MIT.