finish/README.md

# finishte.sh

Command-line completion powered by local LLMs. Press `Tab` twice and get intelligent suggestions based on your terminal context.

## Quick Start

### One-Line Install (Recommended)

```bash
curl -sSL https://git.appmodel.nl/Tour/finish/raw/branch/main/docs/install.sh | bash
```

### Manual Installation

```bash
git clone https://git.appmodel.nl/Tour/finish.git finish
cd finish
./finish.sh install
source ~/.bashrc
```

### Other Installation Methods

See [Installation](#installation) below for package managers, Docker, and more options.

## What It Does

finishte.sh enhances your terminal with context-aware command suggestions. It analyzes:

- Current directory and recent files
- Command history
- Environment variables
- Command help output

Then generates relevant completions using a local LLM.

## Features

**Local by Default**
Runs with LM-Studio on localhost. No external API calls, no data leaving your machine.

**Context-Aware**
Understands what you're doing based on your environment and history.

**Cached**
Stores recent queries locally for instant responses.

**Flexible**
Switch between different models and providers easily.

## Configuration

View current settings:

```bash
finish config
```

Change the endpoint or model:

```bash
finish config set endpoint http://192.168.1.100:1234/v1/chat/completions
finish config set model your-model-name
```

Select a model interactively:

```bash
finish model
```

## Usage

Type a command and press `Tab` twice:

```bash
docker <TAB><TAB>
git commit <TAB><TAB>
ffmpeg <TAB><TAB>
```

Natural language works too:

```bash
# find large files <TAB><TAB>
# compress to zip <TAB><TAB>
```

Test it without executing:

```bash
finish command "your command"
finish command --dry-run "your command"
```

## Installation

### Quick Install (Linux/macOS)

The fastest way to get started:

```bash
curl -sSL https://git.appmodel.nl/Tour/finish/raw/branch/main/docs/install.sh | bash
source ~/.bashrc  # or ~/.zshrc for zsh
finish model
```

### Package Managers

#### Homebrew (macOS)

```bash
brew tap appmodel/finish
brew install finish
finish install
source ~/.bashrc
```

#### APT (Debian/Ubuntu)

Download the `.deb` package from [releases](https://git.appmodel.nl/Tour/finish/releases):

```bash
sudo dpkg -i finish_*.deb
sudo apt-get install -f  # Install dependencies
finish install
source ~/.bashrc
```

### Docker

Run finishte.sh in a container:

```bash
# Build the image
docker build -t finish .

# Run interactively
docker run -it finish

# Or use docker-compose
docker-compose up -d finish
docker-compose exec finish bash
```

Inside the container:
```bash
finish install
source ~/.bashrc
finish model  # Configure your LLM endpoint
```

### From Source

```bash
git clone https://git.appmodel.nl/Tour/finish.git finish
cd finish
chmod +x finish.sh
sudo ln -s $PWD/finish.sh /usr/local/bin/finish
finish install
source ~/.bashrc
```

## Requirements

- Bash 4.0+ or Zsh 5.0+
- curl
- jq
- bc
- bash-completion (recommended)
- LM-Studio or Ollama (for LLM inference)

## Directory Structure

```
~/.finishte/
├── config              # Configuration file
├── finishte.log    # Usage log
└── cache/              # Cached completions
```

## Commands

```bash
finish install    # Set up finishte
finish remove     # Uninstall
finish config     # Show/edit configuration
finish model      # Select model
finish enable     # Enable completions
finish disable    # Disable completions
finish clear      # Clear cache and logs
finish usage      # Show usage statistics
finish system     # Show system information
finish --help     # Show help
```

## Providers

Currently supports:

- **LM-Studio** (default) - Local models via OpenAI-compatible API
- **Ollama** - Local models via Ollama API

Add custom providers by editing `finishte.sh` and adding entries to `_finishte_modellist`.

## Development

### Local Development

Clone and link for development:

```bash
git clone https://git.appmodel.nl/Tour/finish.git finish
cd finish
ln -s $PWD/finishte.sh $HOME/.local/bin/finish
finish install
```

### Running Tests

```bash
# Install BATS testing framework
sudo apt-get install bats  # Ubuntu/Debian

# Run tests
./run_tests.sh

# Or use Docker
docker build -f Dockerfile.test -t finish:test .
docker run --rm finish:test
```

### Building Packages

#### Debian Package

```bash
# Install build dependencies
sudo apt-get install debhelper devscripts

# Build the package
dpkg-buildpackage -us -uc -b

# Package will be created in parent directory
ls ../*.deb
```

#### Docker Images

```bash
# Production image
docker build -t finish:latest .

# Test image
docker build -f Dockerfile.test -t finish:test .

# Using docker-compose
docker-compose build
```

## Distribution & Publishing

### Creating a Release

1. Update version in `finishte.sh` (ACSH_VERSION)
2. Update version in `debian/changelog`
3. Update version in `homebrew/finish.rb`
4. Create and push a git tag:

```bash
git tag -a v0.5.0 -m "Release version 0.5.0"
git push origin v0.5.0
```

This triggers the GitHub Actions workflow which:
- Builds release artifacts
- Creates Debian packages
- Publishes Docker images to GitHub Container Registry
- Creates a GitHub release with downloadable assets

### Homebrew Formula

After creating a release, update the Homebrew formula:

1. Calculate SHA256 of the release tarball:
   ```bash
   curl -sL https://git.appmodel.nl/Tour/finish/archive/v0.5.0.tar.gz | sha256sum
   ```

2. Update `homebrew/finish.rb` with the new SHA256 and version

3. Submit to your Homebrew tap or the main Homebrew repository

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

BSD 2-Clause License. See LICENSE file.