machtiani

Machtiani (mct) is an experimental terminal based, locally ran code chat service. It's designed to work with real projects. Thousands of commits. Thousands of files. For most cases, you’ll get faster, higher quality answers at a fraction of the cost than token-guzzling alternatives. If you run a local model on your laptop, you won't find anything better.

So why vibe when you can fly?

• Efficiently finds right answer based on precise context out of thousands of files in a project.
• Choose any API provider that adheres to OpenAI API spec, including locally ran ollama or mxl-lm.
• Stands on own, but composes in the terminal with other command line tools, such Codex.
• Enjoy this demo video 👉 mct intro<div style="display: flex; align-items: center; text-align: left;">

mct <img src="images/heart-svgrepo-com.svg" alt="heart" width="20" style="vertical-align:middle; margin:0 0.2em;"/> codex

Combine the strongest strengths with --mode answer-only:

• mct excels at understanding large, real codebases — grabbing the right context and returning exactly what needs to be changed, with file paths and functions — at minimal token cost.
• codex is a superb executor for code implementation, refactor, and test runs, but works best when given precise instructions and context.

Example: Compose for Peak Productivity

# Use mct to derive a minimal, context-aware plan and feed it directly to codex:
codex "$(mct \"Add error handling for API calls\" --mode answer-only --model Qwen2.5-Coder-7B-Instruct-Q6)"

• Mix match models: have mct do the heavy lifting with any model of your choice, while codex uses o4-mini (or whatever you want) to implement.
• Lower token usage. mct's highly targeted planning leverages the code/project structure, so LLMs do less redundant thought and token looping.
• Win/Win:
  • Best case: codex can implement the change directly, with step-by-step details and file paths distilled by mct — bypassing expensive, imprecise code search.
  • Worst case: codex still benefits by having all ambiguity boiled out, so it simply fills in implementation details.
• Result: Faster, more precise, and cheaper answers for big projects. When you combine their strengths, you waste less time, fewer tokens — and get more reliable automation at the CLI.

Quick Launch

1. Clone this project.

   git clone --recurse-submodules https://github.com/tursomari/machtiani
   

2. Install mct

   cd mct
   go install \
     -ldflags="$(go run ./generate_ldflags)" \
     ./cmd/mct
   cd -
   

   If you're curious, -ldflags runs mct/generate_ldflags/main.go to set the version (git OID) so that mct can let you know if you're using an incompatible version of the local chat service.

   If mct command isn't found, run this and/or add it as a line in your ~/.bashrc, ~/.zshrc or whatever you use for a shell.

   export PATH="$PATH:$(go env GOPATH)/bin"
   

3. Launch the local chat service.

   Make sure n machtiani project root directory where docker-compose.yml resides.

   docker-compose up --build --remove-orphans
   

4. Set your OpenAI api key and base url.

   export MCT_MODEL_BASE_URL="https://api.openai.com/v1"
   export MCT_MODEL_API_KEY=sk...
   

   If you're using another API provider, for example OpenRouter.

   export MCT_MODEL_BASE_URL="https://openrouter.ai/api/v1"
   export MCT_MODEL_API_KEY=sk...
   

   If the git remote url (e.g. on Github) of the project you intend to use mct with is private (i.e., requires password or api key).

   export CODE_HOST_API_KEY=ghp...
   

   This works for any codehost, so it's not locked into Github.

5. Put a project on machtiani.

   In a git project you want to work on, run

   mct sync --model google/gemini-2.0-flash-001 --model-threads 10
   

   USE A LOW COST and fast model when syncing. If you use Claude or something for syncing, you're just wasting money and time.

   Also, it will only work if you have a git remote origin as a http/s urls (no ssh), at the moment.

   Give it time to finish. Run mct status to check back if completed.

6. Chat with the project

   mct "Ask whatever you want here" --model anthropic/claude-3.7-sonnet:thinking
   

7. Sync any new commits you pushed to your remote origin.

   mct sync --model gpt-4o-mini --model-threads 10
   

   Any local git commits must be pushed to the git remote for mct to sync it.

Local LLMs and quantized models

See the llama.cpp guide for Linux users or the MLX-LM guide for Mac users for setup and best practices if you plan to use mct with a local model instead of an API provider.

Local git-servers

See here if the project you want to chat to is purely local and not on Github or other codehosts.

Configuration

Machtiani can be driven either by environment variables or by a YML machtiani-config file. Environment variables always win if set, but if you prefer to keep your keys and URLs in a file, you can place a .machtiani-config.yml in one of two locations:

1. Project-local <your‐repo‐root>/.machtiani-config.yml
2. Home directory ~/.machtiani-config.yml

Lookup and precedence:

1. If you set an env var (for example MCT_MODEL_API_KEY), it always overrides any value from a config file.
2. Otherwise mct will look for project-local ./.machtiani-config.yml first.
3. Failing that, it will fall back to your home ~/.machtiani-config.yml.
4. If neither exists you must use env vars.

Supported keys in the yaml are exactly the same names as the env vars:

Example of a project-local file (./.machtiani-config.yml):

environment:
  MCT_MODEL_BASE_URL: "https://api.openai.com/v1"
  MCT_MODEL_API_KEY: "sk-REPLACE_WITH_YOURS"
  CODE_HOST_API_KEY: "ghp-REPLACE_WITH_YOURS"
}

You can omit any key that you still prefer to supply via export. Any missing key will simply fall back to its corresponding environment variable (or error out if not set anywhere).

How it Works

Let's sync the commits a project. You must do this whether you have one initial commit or 1,000 commits in history (or more). It will make some inference requests, then locally generate and save some embeddings (cpu + 8GB RAM is just fine).

First, navigate to the directory where the git project resides.

mct sync --model gpt-4o-mini --model-threads 10

Initial sync of a fresh project to mct of a few hundred commits will take a couple minutes and cost few pennies (default is gpt-4o-mini). But once it's done it's done. It saves the data locally.

Time and cost is practically nothing on incremental syncs on new commits. You can sync as many commits as needed (thousands upon thousands).

Speed Up Your Syncs: The sync process is only constrained by how many requests per second you can make to your LLM provider. By increasing --model-threads, you can dramatically speed up syncing. For example, OpenRouter allows 1 request per second for every credit available on your account. With adequate credits and a capable system, using --model-threads 100 could sync thousands of commits in seconds rather than minutes.

mct [prompt] --model gpt-4o-mini

It will apply code changes, if applicable. If it's not in git, it doesn't exist. Just remember that. So if you want to agentically run tests, or some other follow up workflow, use Codex. Codex can also more easily investigate '90% there' or run tests on a slam-dunk by mct, then trying itself from scratch (expensive and gets confused when it gets more complicated).

Now you can choose any model. If you have OpenRouter, you can use any openrouter model. Otherwise, plug in whatever your provider offers and it complies with OpenAI API format.

mct [prompt] --model deepseek/deepseek-r1

Also, you can choose for it not to edit or create new files based on the conversation.

mct [prompt] --mode chat --model gpt-4o-mini

FYI

If we do mct sync with amplify flag, it will drastically increase the accuracy. This is a bail out if your commit history is poor and not well organized, but it costs more. Or if you want to guaranteee absolute peak performance.

mct sync --amplify low --model gpt-4o-mini --model-threads 10

sync --amplify low is about 2 times more costly and somewhat slower.

For example, say we have 15,000 commits. With low amplification, that would be about $0.50 with gpt-4o-mini (default).

But we could instead

mct sync --amplify high --depth 5000 --model gpt-4o-mini --model-threads 10

And that would only sync the most 5000 commits.

But let's scratch that for a sec and say we want all the commits available to machtiani. We could sync 9,999 of the oldest to newest.

git checkout HEAD~5000
mct sync --model gpt-4o-mini --model-threads 10

Then to sync the most recent 5001 commits

git checkout master
mct sync --amplify low --model gpt-4o-mini --model-threads 10

That way we have full coverage.

Peak Performance

sync --amplify high is about 20 times more costly and 5 times slower, compared to only 2 times the cost and somewhat slower with low.

So it's always a good option for incremental syncs and will make sure you have peak performance going forward, or if you're not terribly cost sensitive for initial syncs.

mct CLI Usage

Overview

The machtiani cli mct allows you to interact with the project through command-line parameters. You can provide a markdown file or a prompt directly via the command line, along with various options such as the project name, model type, match strength, and mode of operation.

Command Structure

mct [prompt] [flags]

Flags

Common flags when chatting with a pro