Guide & Reference

Termim is a tool that keeps your terminal history separate for each project folder. It makes sure that when you are working in one project, you don't get distracted by commands you used in a different one.

💻 Developer Scenario

Imagine you are working on a Website and an API. In the Website folder, you use npm run dev. In the API folder, you use python manage.py runserver.

• With normal history: Pressing Up in the API folder might show npm run dev.
• With Termim: Pressing Up in the API folder will only show your Python commands.

How Termim is Built

Termim is designed to be simple, safe, and fast. We follow these rules to make sure it never gets in your way:

• No Background Apps: Termim only runs when you press a key. It doesn't stay open in the background, so it doesn't use your battery or RAM.
• No Internet Needed: Termim never connects to the internet. It doesn't send any of your data anywhere. Everything stays on your computer.
• Safe File Saving: We use special locking to make sure your history is never lost or corrupted, even if you have many terminal windows open at the same time.
• Super Fast: The core is written in Rust, which is very fast. Most actions happen in less than 5 milliseconds, so you won't even notice it's there.

How to Install

Termim comes as a single file that is ready to run. You just need to run one command to set it up.

For Mac and Linux

For Windows (PowerShell)

After you run the command, restart your terminal to start using Termim.

How Folders are Separated

Termim is Directory Context Aware. Instead of trying to guess where your project starts and ends, it treats every unique folder as its own isolated history context.

💻 Developer Scenario

You have a project in ~/code/app-one. Termim looks at your current path and says "This is my current world." It takes that absolute path and creates a unique fingerprint (a hash) to save your history.

If you move to a sub-folder like ~/code/app-one/src, Termim treats that as a new unique context by default. This ensures that the history you see is exactly what you did in that specific spot.

Finding Your History

Termim looks for your commands in three steps to make sure you always find what you need:

• Step 1: It looks for commands you used in the current folder.
• Step 2: If it can't find anything there, it looks through all your other projects.
• Step 3: If it still can't find a match, it uses your normal terminal history.

💻 Developer Scenario

You are in a brand new project folder. You press Up.

1. Termim sees the folder is empty.
2. It automatically looks at your "Global" history and shows the git clone or npm install commands you used in other projects.
3. This helps you set up new projects using the same patterns you used before.

What We Save

Every time you run a command, Termim saves a few extra details to help it stay organized:

• Did it work? (Exit Code)
• When? (Date and Time)
• Which branch? (Git Branch name)
• Where? (Folder Path)

💻 Developer Scenario

If you run a command that fails (like a typo gti status), Termim notes that the result was an error. Later, when you press Up, it will prioritize the successful git status and hide the typo.

Smart Suggestions

Termim learns from your habits. It looks at which commands you usually run together.

💻 Developer Scenario

You frequently do this sequence:

Termim learns that "Step 2" usually follows "Step 1". Next time you type git add . and press Enter, the very next time you press Up (or Down on an empty prompt), git commit will be the first thing you see.

Hiding Mistakes

Termim tries to be helpful by hiding your mistakes. It uses the "Exit Code" of your commands to decide what to show you.

💻 Developer Scenario

You type npm run devv by mistake. It fails. Then you type npm run dev and it works. Termim will "down-weight" the mistake. Your history stays clean, showing only the commands that actually did something useful.

Hiding Secrets

Termim has a built-in "scrubber" that hides sensitive information before it is saved to your computer.

💻 Developer Scenario

You run this command to set a password:

Termim sees the password and saves it like this instead:

Your secrets are never saved in plain text in your history files.

The 'init' command

This command registers your current folder as a "Project Root." If you run termim init in a folder, Termim will treat that folder and all its sub-folders as a single unified project history. This is helpful for large projects with many sub-directories.

The 'query' command

This is the main search tool. It looks up your history for the current folder. It can take extra options:

• --history-only: Only shows commands you used in this folder (Recency mode).
• --suggest-only: Only shows predicted commands (Transition mode).
• --branch: Filters history for a specific Git branch.

The 'log' command

This command saves a new command to your history. It is called automatically by your shell. It takes these details:

• command_str: The text of the command you ran.
• --exit: The numeric result (so Termim knows if it worked).
• --prev: The command you ran right before this one (to learn your habits).

The 'suggest' command

This is used to get a list of what you should type next. It can take a prefix (like "git") to filter the suggestions so they only show commands starting with that word.

The 'doctor' command

This runs a health check. It verifies if your shell scripts are installed correctly, checks if your history files are readable, and benchmarks how fast Termim is running.

The 'stats' command

This shows your usage patterns. It tells you how many different projects Termim is tracking and how many commands you have saved across your entire computer.

The 'update' command

Checks if there is a newer version of Termim available on GitHub. It compares your current version with the latest release.

The 'clear' command

Deletes your history and statistics. Use --force if you want to skip the confirmation prompt. Warning: This cannot be undone.

The 'uninstall' command

Completely removes Termim from your system. It deletes the binary, your history files, and tries to clean up your shell profile.

Your Data is Yours

All your data stays on your own computer. Termim never sends your data to any servers or trackers. You have total control.

• Mac/Linux: ~/.termim/
• Windows: C:\Users\[YourName]\.termim\

If you want to move your history to a new computer, just copy that folder. It's that simple.