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), giving them persistent memory for research, plans, and context across sessions.

[!WARNING] This project incorporates code, comments, or 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?
• 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.

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.

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>]	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 agents init	Install AI agent integration
thts agents uninit	Remove AI agent integration

Documentation

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

AI Agent Integration

thts integrates with AI coding agents to give them awareness of your thoughts directory. Supports Claude Code, OpenAI Codex, and OpenCode.

thts agents init              # Install for detected agents
thts agents init -i           # Interactive mode
thts agents init --global     # Install to global config directories
thts agents uninit            # Remove integration

This installs skills, commands, and agents for thoughts/ integration including:

• /thts-integrate - Activate thoughts/ awareness for current task
• /thts-handoff, /thts-resume - Session handoff and resume
• Specialized agents for searching/analyzing thoughts

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 instructions/, skills/, commands/, and agents/ directories.

The file structure supports multiple agent tools (Claude, Codex, OpenCode):

instructions/thts-instructions.md - Shared thts instructions for all agents
skills/{agent}/*.md               - Agent-specific skills (flat for Claude)
skills/{agent}/*/SKILL.md         - Agent-specific skills (subdirs for Codex/OpenCode)
commands/{agent}/*.md             - Agent commands (prompts for Codex, global-only)
agents/{agent}/*.md               - Agent definitions per tool

Index

• Variables
• func GetDefaultSettings(filename string) string

Variables

var ClaudeAgents embed.FS

ClaudeAgents contains embedded agent files for Claude Code.

var ClaudeCommands embed.FS

ClaudeCommands contains embedded command markdown files for Claude Code.

var ClaudeSkills embed.FS

ClaudeSkills contains embedded skill markdown files for Claude Code. Claude uses flat files: skills/claude/skill-name.md

var CodexAgents embed.FS

CodexAgents contains embedded agent files for Codex CLI.

var CodexCommands embed.FS

CodexCommands contains embedded prompt markdown files for Codex CLI. Codex calls these "prompts" and they're global-only.

var CodexSkills embed.FS

CodexSkills contains embedded skill files for Codex CLI. Codex uses subdirectories: skills/codex/skill-name/SKILL.md

var Instructions embed.FS

Instructions contains the shared thts-instructions.md file.

var OpenCodeAgents embed.FS

OpenCodeAgents contains embedded agent files for OpenCode.

var OpenCodeCommands embed.FS

OpenCodeCommands contains embedded command markdown files for OpenCode.

var OpenCodeSkills embed.FS

OpenCodeSkills contains embedded skill files for OpenCode. OpenCode uses subdirectories: skills/opencode/skill-name/SKILL.md

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 GetDefaultSettings

func GetDefaultSettings(filename string) string

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