gotchi

README

gotchi

terminal pets generated from your projects.

Built with go-identicon 👾
Powered by bubbletea 🧋

installation

go install github.com/amilleah/gotchi@latest

Launch by typing gotchi in your terminal.

Note: Ensure your Go binary path (usually ~/go/bin) is added to your system $PATH.

features

deterministic identities

• c-time (creation time): The folder's original creation date and name are used to seed the sprite generator and core traits.
• stable traits: The seed is fixed to the project's origin, so your gotchi's identicon, rarity, and category (logical, chaos, etc.) will not change.

dynamic personalities

• m-time (modification time): Every time you change a file in your project, your gotchi’s quirks (likes and dislikes) are reshuffled.
• xp & leveling: Experience points are calculated based on the "active lifespan" (time between c-time and m-time) using logarithmic scaling to reward growth with diminishing returns.

social ecosystem

• mood states: Gotchi transition between active, happy, bored, or grumpy based on recent file activity and their interactions with other pets.
• interaction logic: Gotchi interact in the "park" based on their current quirks:
  • bonding (❤): Triggered when two neighbors share a common "like."
  • storming (⛈): Occurs when neighbors bond over shared "dislikes."
  • greeting (hi!): A shared "hello."
• interactive park: Press Enter to shuffle the placement of your gotchi in the grid.

configuration

gotchi searches for a gotchi.yaml in the following order:

• Local: The current working directory.
• Global: ~/.config/gotchi/gotchi.yaml (or system equivalent).

project_root: /path/to/Projects

Note: You can also add a .gotchiignore file inside your project_root to exclude specific directories (one name per line).

troubleshooting

Can't run from the command line? Make sure Go is in your $PATH.
Gaps in icons? Set your terminal line spacing to 1.0.