thtsfiles

README

thts

A CLI for storing developer thoughts, plans, and dreams in a central repo while keeping them accessible in any project. Integrates with AI coding agents (Claude Code, Codex, OpenCode, Gemini CLI, and Pi), giving them persistent memory for research, plans, and context across sessions.

[!WARNING] This project incorporates code, comments, and documentation generated or assisted by artificial intelligence tools (such as Claude or ChatGPT). All content is actively reviewed and modified by project maintainers before inclusion. Use at your own risk.

• How It Works
• Why thts?
• Installation
  • Go Install
  • Binary Downloads
• Quick Start
• Commands
• Documentation
• AI Agent Integration
• Attribution
• Compatibility with HumanLayer
  • Config handling
• License

How It Works

Your notes live in a central thoughts repo (e.g., ~/thoughts/). When you run thts init in a project, it creates symlinks so notes appear locally:

~/src/myproject/thoughts/     # Symlinks (git-ignored)
├── {user}/   →  ~/thoughts/repos/myproject/{user}/
├── shared/   →  ~/thoughts/repos/myproject/shared/
└── global/   →  ~/thoughts/global/

Editing thoughts/{user}/notes.md in your project actually edits the file in your central thoughts repo. Changes sync automatically on commits.

[!TIP] The central thoughts repo can live inside an Obsidian vault. It's all markdown at the end of the day.

Why thts?

thts stores thoughts, plans, dreams, research, etc. in one central repo and links it to existing repos so that they can be shared across projects and with teams without versioning them in every repo independently.

• Access notes in every project
  • "thoughts" appear as a local thoughts/ directory via symlinks in each enabled repo/project
• Never lose context
  • Notes sync to a central git repo and can be queried from anywhere
• Share with a team
  • By design notes can be given a personal, project, or team scope
• Automatic LLM integration
  • AI agents will automatically, if configured, use thts to keep track of research, notes, plans, etc.

[!NOTE] thts is a Go reimplementation of the thoughts subcommand from HumanLayer's CLI (humanlayer). See Compatibility with HumanLayer for more information.

Installation

Go Install

go install github.com/scottames/thts/cmd/thts@latest

Binary Downloads

Pre-built binaries for Linux and macOS (amd64/arm64) are available on the GitHub Releases page.

Quick Start

# First-time setup (once per machine)
thts setup

# Initialize in any git repo
cd ~/src/myproject
thts init

# Start writing
echo "# Architecture Notes" > thoughts/$user/architecture.md

# Sync with central remote repo
#  - If integrated with Claude, Claude will be instructed to do so automatically
thts sync -m "Added architecture notes"

Commands

Command	Description
thts setup	First-time configuration
thts init [--profile <name>] [--no-agents]	Initialize thoughts in current repo (uses default profile)
thts sync [-m <message>]	Sync thoughts to central repo
thts status	Show thoughts status
thts uninit	Remove thoughts from current repo
thts config [--edit]	View/edit configuration
thts profile create <name>	Create a profile
thts profile list	List profiles
thts profile show <name>	Show profile details
thts profile delete <name>	Delete a profile
thts init agents	Install AI agent integration
thts uninit agents	Remove AI agent integration

Documentation

• User Guide - Complete documentation
• Troubleshooting - Common issues and solutions

AI Agent Integration

thts integrates with Claude Code, OpenAI Codex CLI, OpenCode, Google Gemini CLI, and Pi to give them awareness of your thoughts directory.

thts init agents              # Install for detected agents
thts init agents -i           # Interactive mode
thts init agents --global     # Install to global config directories
thts init agents --agents pi  # Install Pi's project integration only
thts uninit agents            # Remove integration

This installs skills, commands or prompts, and native runtime adapters where the selected agent supports them. Agents with native sub-agent support also receive the thoughts search and analysis agents. The shared resources include:

• /thts-integrate - Activate thoughts/ awareness for current task
• /thts-handoff, /thts-resume - Session handoff and resume
• thoughts-locator and thoughts-analyzer where supported

Pi installs .pi/skills/thts-integrate/SKILL.md, prompt templates in .pi/prompts/, and its thts-integration.ts extension in .pi/extensions/. Pi loads project-local resources only after the project is trusted; use pi --approve for a one-run override in non-interactive use.

See User Guide for details.

Attribution

This project is inspired by and based on the thoughts subcommand from HumanLayer by the HumanLayer Authors.

The original implementation provided the design, directory structure, and config format that thts replicates for compatibility. Thanks to the HumanLayer team for creating and open-sourcing this workflow.

Compatibility with HumanLayer

thts is a Go reimplementation of HumanLayer's humanlayer thoughts subcommand. They share:

• Directory structure (~/thoughts/repos/<project>/)
• Symlink layout in projects
• Git hooks

Config handling

thts uses its own config at ~/.config/thts/config.yaml (YAML format). It can read HumanLayer's config (~/.config/humanlayer/humanlayer.json) as a fallback, but never writes to it. This means:

• Migrating from HumanLayer to thts is seamless - existing config is read automatically
• thts writes its own config, so HumanLayer won't see changes made via thts
• Team members can use whichever tool they prefer on the same thoughts repo

See the Compatibility Guide for details.

License

Apache License 2.0 - see LICENSE for details.

Documentation

Overview

Package thtsfiles provides embedded agent integration files for thts. This package exists at the repo root to enable go:embed access to the embedded/ directory containing all agent integration assets.

Template files in embedded/ are rendered at copy time with agent-specific data.

Index

• Variables
• func GetAvailableAgents() []string
• func GetAvailableCommands() []string
• func GetAvailableHooks() []string
• func GetAvailableSkills() []string
• func GetDefaultReadme(data ReadmeData) (string, error)
• func GetDefaultSettings(templateName string) string
• func GetInstructions(data InstructionsData) (string, error)
• func RenderAgent(agentType agents.AgentType, agentName string) (string, error)
• func RenderCommand(agentType agents.AgentType, cmdName string) (string, error)
• func RenderHook(agentType agents.AgentType, hookName string) (string, error)
• func RenderSkill(agentType agents.AgentType, skillName string) (string, error)
• type CategoryRow
• type InstructionsData
• type ReadmeData

Variables

var Defaults embed.FS

Defaults contains embedded default files for the thoughts repository. Currently includes the root README.md created during setup.

var EmbeddedTemplates embed.FS

EmbeddedTemplates contains the consolidated template files for all agents. Templates are rendered at copy time with agent-specific data.

var Instructions embed.FS

Instructions contains the shared thts-instructions.md file.

var OpenCodePlugins embed.FS

OpenCodePlugins contains embedded plugin files for OpenCode.

var PiExtensions embed.FS

PiExtensions contains embedded extension files for Pi.

var Settings embed.FS

Settings contains embedded default settings files for agents. Files are named by agent type: codex.toml, opencode.json, etc. Claude settings are built dynamically and not embedded.

var Templates embed.FS

Templates contains embedded template files for thoughts/ documents. These are copied to thoughts/.templates/ during init.

Functions

func GetAvailableAgents

func GetAvailableAgents() []string

GetAvailableAgents returns the list of available agent template names.

func GetAvailableCommands

func GetAvailableCommands() []string

GetAvailableCommands returns the list of available command template names.

func GetAvailableHooks

func GetAvailableHooks() []string

GetAvailableHooks returns the list of available hook template names.

func GetAvailableSkills

func GetAvailableSkills() []string

GetAvailableSkills returns the list of available skill template names.

func GetDefaultReadme

func GetDefaultReadme(data ReadmeData) (string, error)

GetDefaultReadme returns the default README.md content for the thoughts repository. It uses Go templates to replace placeholders with the provided values.

func GetDefaultSettings

func GetDefaultSettings(templateName string) string

GetDefaultSettings returns the default settings content for a template identity. Returns empty string if no default settings exist (e.g., Claude builds dynamically).

func GetInstructions

func GetInstructions(data InstructionsData) (string, error)

GetInstructions returns the rendered thts-instructions.md content. It executes the embedded template with the provided data.

func RenderAgent

func RenderAgent(agentType agents.AgentType, agentName string) (string, error)

RenderAgent renders an agent template for a specific agent type. Returns the rendered markdown content.

func RenderCommand

func RenderCommand(agentType agents.AgentType, cmdName string) (string, error)

RenderCommand renders a command template for a specific agent type. Returns the rendered markdown content, or TOML for Gemini.

func RenderHook

func RenderHook(agentType agents.AgentType, hookName string) (string, error)

RenderHook renders a hook template for a specific agent type. Returns the rendered shell script content.

func RenderSkill

func RenderSkill(agentType agents.AgentType, skillName string) (string, error)

RenderSkill renders the skill template for a specific agent type. Returns the rendered markdown content.

Types

type CategoryRow

type CategoryRow struct {
	Name        string // Category name, e.g., "research" or "plans/complete"
	Description string // Human-readable description
	Location    string // Path like "thoughts/shared/research/"
	Trigger     string // Optional auto-save trigger description
	Template    string // Template filename, e.g., "research.md"
}

CategoryRow represents a category for template rendering in instructions.

type InstructionsData

type InstructionsData struct {
	User       string        // Username from config
	Categories []CategoryRow // Flattened list including sub-categories
}

InstructionsData holds all data for rendering thts-instructions.md.

type ReadmeData

type ReadmeData struct {
	Profile   string
	ReposDir  string
	GlobalDir string
}

ReadmeData holds the template data for the thoughts repo README.