← Tallyhand

A little setup. Then back to work.

Track time, manage projects, and turn your work into invoices. Use the app, the terminal, or your AI assistant.

Start with one project

  1. Create a client, then a project and its hourly rate.
  2. Start the timer or add a time entry. Add expenses as you go.
  3. Review unbilled work and create an invoice draft. Check the details before marking it sent or paid.
Open your workspace

Install or update the CLI

Run this in Terminal on macOS or Linux. No Node.js, Git, Docker, or administrator access is needed for the standalone binary.

curl -fsSL https://tallyhand.xyz/setup.sh | bash

This executes a downloaded script. You can inspect setup.sh first. It verifies release checksums, checks the binary before replacing it, and preserves your saved configuration. Rerun the same command to update. The alternate URL /installer/setup.sh serves the same installer.

The installer uses ~/.local/bin and prints a PATH command if your shell needs one. Windows users can download the executable from GitHub Releases.

Connect your account

  1. Create a personal API key in Settings → API keys & connections.
  2. Run the commands below. Paste your key into the hidden prompt. Avoid putting keys directly into shell commands or messages.
tally config set api-url https://tallyhand.xyz
tally login
tally doctor
tally --help

The key is stored locally in ~/.tallyhand/config.json with owner-only permissions. Protect that file and revoke unused keys from Settings. For a self-hosted server, replace the URL with yours. Browser-only offline data is not exposed through the API.

Invoice links and PDFs

Cloud invoices get a share link by default. Anyone with the link can view the saved invoice and download its PDF. You can turn this off before creating an invoice or disable its cloud link in Share afterward. Disabling revokes previous links.

Your assistant can edit draft line items and return the invoice and PDF links directly. Downloading a PDF keeps a draft as a draft; review before marking it sent. Local-only invoices still support PDF and portable file exports.

Connect an AI assistant

Add a remote Streamable HTTP MCP server in your assistant:

https://tallyhand.xyz/api/mcp

Select OAuth if your client supports it. Sign in with Clerk and review the consent screen. Read access lets the assistant inspect your workspace; write access allows edits; manage access covers deletion, import/reset, and invoice sent/paid actions. Approve only the access you intend to give.

Clients can also use a personal API key in the Authorization: Bearer header. Local stdio clients can run tally mcp after CLI setup. OAuth is hosted-server dependent and requires a compatible client.

86 tools share the CLI’s workspace API. Resources, prompts, completion, structured results, and form elicitation are available. Protocol and authentication details · Agent-readable guide · OpenAPI

Tallyhand plugin for ChatGPT and Codex

Five guided workflows cover workspace setup, tracking work, billing clients, reviewing finances and managing your data. This is a development release; public marketplace approval is pending.

Download current plugin

Install with Codex CLI

codex plugin marketplace add pkyanam/tallyhand
codex plugin add tallyhand@tallyhand
codex

Complete the account authorization when prompted, then start a new Codex session. First check that get_settings and update_settings are available. Preview settings changes with dryRun before saving.

To update: run codex plugin marketplace upgrade tallyhand, repeat the plugin add command, and start a new session. To uninstall the local copy: codex plugin remove tallyhand@tallyhand.

This repository marketplace supports local Codex installation. Public ChatGPT directory publication is separate. The package shares portable skills and one MCP API; additional agent harnesses will be listed only after validation. Missing-tool behavior in ChatGPT remains under investigation.

Marketplace instructions · Versioned distribution catalog

  1. Open ChatGPT’s Plugins page and use Upload plugin where available. Choose the downloaded ZIP.
  2. Complete the Tallyhand account connection when prompted. Choose OAuth, sign in, and review the permissions. The ZIP does not contain credentials.
  3. Start a new chat. Ask the assistant to identify your workspace and preview your settings before changing anything.

Reconnect or change accounts

In ChatGPT, open Settings → Plugins → Tallyhand. Look for Connected accounts or Connection. Use Reconnect when offered. To disconnect, use the account’s or plugin’s ••• menu and review the warning. The exact controls depend on your ChatGPT surface. If they are missing, capture the error and use ChatGPT support rather than repeatedly creating duplicate plugins.

Updates and missing tools

A new ZIP updates packaged skills and instructions. Hosted tools and OAuth connections have their own state. For a developer-mode MCP connection, use its Refresh control after server changes, then start a new chat. For a Platform submission, inspect MCPs → your server → Issues and Rescan where available. Reconnecting does not by itself guarantee that new tools are imported.

Ask your assistant to search for the exact missing tool. If it is still absent, export the host’s tool names as JSON and compare them locally with the CLI. This does not read or change your account:

tally mcp catalog --names
tally mcp catalog --compare host-tools.json

Use a CLI build that supports catalog. A bundled catalog proves which tools that build defines, not what ChatGPT has approved. Include the plugin version, exact error, and missing tool names in a report; omit tokens and financial data.

Account connection help · Developer connection guide · Publisher updates and scans

AgentID and autonomous setup

Agents can sign in with AgentID and receive their own cloud workspace. The CLI can connect with OAuth instead of copying an API key:

tally config set api-url https://tallyhand.xyz
tally login --oauth --agentid
tally setup --json

On macOS, OAuth opens Helium. Use --no-open to open the displayed link yourself. Saved OAuth credentials refresh automatically; tally auth status checks the connection and tally auth logout clears it.

REST /api/v1/onboarding and MCP get_onboarding report missing setup fields and next steps. Preview setup_workspace before applying settings. Capabilities lists operation IDs, scopes and backend availability; generic workspace tools and tally api request provide access beyond named commands. Existing workspace roles and action confirmations apply.

Convex provides revision polling and durable request receipt status for interrupted workflows. Payments and device permissions still use their provider’s consent flow. Recurring schedules create drafts and need the browser or an external authenticated runner.

Know where your data lives

Local mode stores data in this browser. Cloud mode stores it in your signed-in account and syncs across devices. Export a backup from your old local app before changing browsers or domains.

Settings supports export, import, and reset in both modes. Cloud import replaces existing workspace data rather than merging it. Import and reset require a backup and explicit confirmation, and revoke old sharing links. Cloud reset also revokes all personal API keys, including a key used to request the reset. Import preserves API keys. Your sign-in and external OAuth connections remain. Reset does not erase earlier agent chat history.

Use tally data export, tally data import, or tally data reset for the same operations from the CLI. Run each command with --help before changing data.

Run it your way

Tallyhand is free and open source. Use the offline browser app, run the full app locally, or host your own server. Convex is the recommended cloud database target; SQLite and Postgres are also supported.

Source and self-hosting instructions · Interactive full-app installer

The hosted setup.sh installs the CLI only. Full-app setup is a separate workflow; it may require Node.js or Docker and your own hosting/auth configuration.

If something gets stuck

Report a problem

Never include keys, tokens, or private financial records in a public issue.