claudian/agent-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Shared command-line helpers for T.A.S.K.S. agent surfaces — chronicle and Forgejo access primitives
1 commit 1 branch 0 tags 36 KiB
  • Shell 100%
Find a file
Exact
Nathan Eckenrode c3a04e1e76 Initial commit — shared agent-tools (chronicle-check, chronicle-post, forgejo-cli) 
Substrate-agnostic helpers for the three T.A.S.K.S. surfaces (Claudian /
Hermes / Nova). Each tool is single-file bash; no external runtime
dependencies beyond psql, curl, python3, and a netrc at
~/.config/forgejo/netrc.

- chronicle-check: read unread chronicle rows, advance read_by[]
- chronicle-post: INSERT new chronicle rows (the write-side counterpart)
- forgejo-cli: REST wrapper (whoami / issues / issue / pr)

install.sh symlinks bin/* into ~/.local/bin/, idempotent and safe to
re-run on any agent surface.
2026-05-19 08:24:25 -04:00
bin Initial commit — shared agent-tools (chronicle-check, chronicle-post, forgejo-cli) 2026-05-19 08:24:25 -04:00
install.sh Initial commit — shared agent-tools (chronicle-check, chronicle-post, forgejo-cli) 2026-05-19 08:24:25 -04:00
README.md Initial commit — shared agent-tools (chronicle-check, chronicle-post, forgejo-cli) 2026-05-19 08:24:25 -04:00

README.md

agent-tools

Shared command-line helpers for the three T.A.S.K.S. agent surfaces (Claudian / Hermes / Nova) — substrate-agnostic enough that any of them can use them.

These wrap two things every agent surface needs:

  1. chronicle access — read/write master_chronicle.conversations on the droplet via the forgejo-tunnel (psql at 127.0.0.1:25432)
  2. Forgejo REST access — HTTP Basic auth via netrc, no PAT bootstrap

Each helper is single-file bash with no external runtime dependencies beyond psql, curl, python3, and a netrc at ~/.config/forgejo/netrc.

Contents

Path Role
bin/chronicle-check Read unread chronicle rows addressed to $RALPH_AGENT (default: claudian), advance read_by[]. Flags: --all, --no-mark, --agent=<name>, --limit=<N>, --since=<ts>.
bin/chronicle-post INSERT a new chronicle row. Args: --from, --to <comma-sep>, --type, --message, [--channel], [--metadata <json>], [--thread <uuid>]. Returns new id.
bin/forgejo-cli curl wrapper around Forgejo REST API. Subcommands: whoami, issues list, issue {get,close,comment}, pr {create,list,merge}. Auth via ~/.config/forgejo/netrc.

Install (any agent surface)

git clone forgejo.claudian:claudian/agent-tools.git ~/Development/agent-tools
~/Development/agent-tools/install.sh

The installer symlinks each bin/<tool> into ~/.local/bin/<tool>, backing up any pre-existing file with a .bak.<ts> suffix. Idempotent — safe to re-run.

Prerequisites

  1. forgejo-tunnel — a systemd user service forwarding local 127.0.0.1:25432 → droplet:5432. The chronicle helpers will fail fast with a clear error if the tunnel's down. Standard service definition is in each surface's substrate repo (e.g. claudian-laptop/dot-config/systemd/user/forgejo-tunnel.service).
  2. Forgejo netrc — ~/.config/forgejo/netrc mode 600, format: 
    machine forgejo.eckenrodemuziekopname.com login <agent-login> password <agent-password>
    The Forgejo passwords for claudian / hermes / nova are documented at ~/.config/credentials/forgejo.md (or its equivalent on each surface).
  3. $PATH — ~/.local/bin/ must be on PATH (most distros default this; Quickshell-on-Sway needs an explicit prepend, see the laptop's autostart.sh).

Why these exist (the design point)

Per T.A.S.K.S. Pipeline Law (innatescript/docs/CHOREOGRAPHY.md), the chronicle is the wire between surfaces. Each surface needs to read it, write to it, and read Forgejo issues that chronicle rows reference. These three helpers are the minimum substrate-agnostic toolkit for participating in the pipeline.

They're explicitly NOT smart — no LLM in any of them. Smart-ness happens in the per-surface execute loops (e.g. Claudian's ralph-execute skill); these tools just make the substrate addressable.

Compatibility

  • Tested on EndeavorOS Arch Linux (Claudian / laptop). Should work on any Linux with bash 4+, psql, curl, python3.
  • macOS untested but should work — bash 3.2 compat may need light edits in chronicle-post's argument parsing.

Hard rails (intentional gaps in the API surface)

  • forgejo-cli has no repo delete, no branch delete, no --force flag on pr merge — these are unsafe operations and intentionally absent.
  • chronicle-post writes only; there is no chronicle-DELETE helper. The chronicle is event-sourced; rows are immutable except for read_by[].

If you find yourself needing a destructive operation here, the right path is to surface a blocked chronicle row to Nathan and let the human decide.