doc: how does it compare to x

Signed-off-by: blob42 <contact@blob42.xyz>

Author: blob42

README.md

@@ -26,6 +26,21 @@ Although this fork introduces breaking changes and a substantial rewrite, I've t
 
 In particular, the model definition flow was carefully designed to quickly add custom model profiles for specific cases and easily switch between them or assign them to custom commands.
 
+**[How Does It Compare To X](./doc/how-does-it-compare-to.md)**
+
+**[Demo](#commands)**
+
+**[Configuration](#configuration)**
+
+**[Command Definition](#configuration)**
+
+**[Model Specification](#model-specification)**
+
+**[Templates](#templates)**
+
+**[Example Config](#example-configuration)**
+
+
 
 ## Installation
 
@@ -175,7 +190,7 @@ require("codegpt").setup({
 })
 ```
 
-### Overriding Command Configurations
+### Overriding Command Definitions
 
 The configuration table `commands` can be used to override command configurations.
 
@@ -205,6 +220,56 @@ commands = {
 }
 ```
 
+### Model Specification
+
+The `models` table defines available LLM models for each provider. Models are
+organized by provider type and can inherit parameters from other models.
+
+```lua
+  models = {
+    default = "gpt-3.5-turbo",              -- Global default model
+    ollama = {
+      default = "gemma3:1b",                -- Ollama default model
+      ['qwen3:4b'] = {
+        alias = "qwen3",                    -- Alias to call this model
+        max_tokens = 8192,
+        temperature = 0.8,
+        append_string = '/no_thinking', -- Custom string to append to the prompt
+      },
+    },
+    openai = {
+      ["gpt-3.5-turbo"] = {
+        alias = "gpt35",
+        max_tokens = 4096,
+        temperature = 0.8,
+      },
+    },
+  }
+```
+
+#### Inheritance
+
+Models can inherit parameters from other models using the `from` field. For example:
+```lua
+    ["gpt-foo"] = {
+      from = "gpt-3.5-turbo",  -- Inherit from openai's default
+      temperature = 0.7,       -- Override temperature
+    }
+```
+
+#### Aliases
+
+Use `alias` to create shorthand names for models.
+
+#### Override defaults
+
+Specify model parameters like `max_tokens`, `temperature`, and `append_string`
+to customize behavior. see `lua/codegpt/config.lua` file for the full config specification.
+
+#### Model Selection
+
+- Call `:lua codegpt.select_model()` to interactively choose a model via UI.
+
 ### UI Configuration
 
 ```lua
@@ -236,6 +301,8 @@ hooks = {
 
 ## Templates
 
+You can use macros inside the user/system message templates when defining a command. 
+
 The `system_message_template` and `user_message_template` can contain template macros. For example:
 
 | macro | description |
@@ -246,6 +313,39 @@ The `system_message_template` and `user_message_template` can contain template m
 | `{{command_args}}` | Everything passed to the command as an argument, joined with spaces. |
 | `{{language_instructions}}` | The found value in the `language_instructions` map. |
 
+### Template Examples
+
+Here is are a few examples to demonstrate how to use them:
+
+```lua
+  commands = {
+  --- other commands
+    cli_helpgen = {
+      system_message_template = 'You are a documentation assistant to a software developer. Generate documentation for a CLI app using the --help flag style, including usage and options. Only output the help text and nothing else.',
+      user_message_template = 'App name and usage:\n\n```{{filetype}}\n{{text_selection}}```\n. {{command_args}}. . {{language_instructions}}',
+      model = 'codestral',
+      language_instructions = {
+        python = 'Use a standard --help flag style, including usage and options, with example usage if needed.',
+      },
+    },
+    rs_mod_doc = {
+      system_message_template = 'You are a Rust documentation assistant. Given the provided source code, add appropriate module-level documentation that goes at the top of the file. Use the `//!` comment format and example sections as necessary. Include explanations for what each function in the module.',
+      user_message_template = 'Source code:\n```{{filetype}}\n{{text_selection}}\n```\n. {{command_args}}. Generate the doc using module level rust comments `//!` ',
+    },
+
+    -- dummy command to showcase the use of chat_history
+    acronym = {
+      system_message_template = 'You are a helpful {{filetype}} programming assistant that abbreviates identifiers and variables..',
+      user_message_template = 'abbreviate ```{{filetype}}\n{{text_selection}}```\n {{command_args}}',
+      chat_history = {
+        { role = 'user', content = 'abbreviate `configure_user_script`' },
+        { role = 'assistant', content = 'c_u_s' },
+        { role = 'user', content = 'abbreviate ```lua\nlocal = search_common_pattern = {}```\n' },
+        { role = 'assistant', content = 'local = s_c_p = {}' },
+      },
+    },
+```
+
 ## Callback Types
 
 | name      | Description |

doc/how-does-it-compare-to.md

@@ -0,0 +1,27 @@
+
+## Rationale
+
+There are dozens of vim/neovim AI plugins, but I've always favored the minimalist design and efficient workflow of the original `CodeGPT.nvim` plugin. When I noticed the project was no longer actively maintained, I began patching it to meet my needs. Eventually, I decided to fork the project and clean up the codebase, adding documentation for new features in hopes of helping others who value simplicity and speed.
+
+My workflow is heavily focused on Ollama, so most testing has been done with the Ollama API and OpenAI-compatible endpoints. Contributions are always welcome.
+
+## How Does It Compare To X
+
+The goal of `codegpt-ng` is not to outperform other plugins or replicate the functionality of tools like Copilot or Cursor. Instead, it prioritizes minimalism and seamless integration with Vim's native capabilities. Review the demos to see if this approach aligns with your coding style.
+
+### Key Differentiators
+
+- **Templates**: The standout feature of `codegpt-ng` is its powerful [template system](../README.md#templates), enabling users to define custom commands quickly without writing Lua code.
+
+---
+
+### CodeCompanion
+
+CodeCompanion aims to deliver a full AI-first development experience akin to Cursor, offering a wide array of features. While this may suit some users, I find many of these features unnecessary or easily achievable on `codegpt-ng` with minimal overhead and cognitive load. For developers who prefer lightweight tools with high customizability, `codegpt-ng` is a better fit.
+
+---
+
+### Ollama.nvim
+
+- **Recommended for**: Users seeking an Ollama management interface alongside AI capabilities.
+- **codegpt-ng's Advantage**: Full Ollama compatibility with the flexibility to switch models, define custom configurations, and tailor parameter mixes for specific commands or use cases—all without requiring additional plugins or complex setups.