Ness Agent

Ness Agent is an experimental, hackable coding-agent harness for engineers who want to own the loop. It ships as a Python SDK you can embed in your own tools and Ness, an interactive CLI for day-to-day coding sessions.

NessAgent TUI in Act mode.

0.x experimental — APIs may change until 1.0. See CHANGELOG.

Table of contents

• Overview
• Installation
• Quick start — CLI (Ness)
• Quick start — SDK
• Documentation
• Contributing
• License

Overview

Both are included in the ness-agent PyPI package. OpenRouter-compatible chat models, native tool-calling, cache-safe summary compaction, and filesystem-driven extension points under .ness/.

Installation

Requires Python 3.12+.

CLI — global install (recommended)

On Linux/Mac Os:

curl -fsSL https://nessagent.dev/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://nessagent.dev/install.ps1 | iex"

Or install it directly with uv or pipx:

uv tool install --upgrade ness-agent
# or: pipx install ness-agent

Launch ness and run /login to use either a Codex subscription or an OpenRouter API key. Codex sign-in uses the installed codex CLI's managed browser/device flow and stores credentials in Ness's isolated global config directory; it never reads or changes ~/.codex.

For environment-based OpenRouter setup:

export OPENAI_API_KEY=your-openrouter-api-key
export OPENAI_BASE_URL=https://openrouter.ai/api/v1

Add those lines to ~/.bashrc or ~/.zshrc to persist across sessions. Alternatively, /login accepts and masks the key (stored in global secrets.json).

Ness does not automatically read or migrate a project .env file. You may still keep local values in .env, but load them into the process explicitly (for example, uv run --env-file .env ness) or use /config.

Optional tracing support:

uv tool install 'ness-agent[tracing]'

Ensure ~/.local/bin (uv) or pipx's bin directory is on your PATH.

SDK — library install

For embedding the agent harness in your own Python project (use a venv):

pip install ness-agent
pip install 'ness-agent[tracing]'   # optional

# In a uv-managed project (adds to pyproject.toml):
uv add ness-agent
uv add ness-agent --extra tracing   # optional

From source (contributors):

git clone https://github.com/Sagnnik/ness-agent.git
cd ness-agent
uv sync
uv run ness

Editable global install from a clone:

git clone https://github.com/Sagnnik/ness-agent.git
cd ness-agent
uv tool install -e .
ness

Quick start — CLI (Ness)

ness
/init                       # create .ness/ and global config

Headless one-shot:

ness -p "what does the auth module do?"

Parallel isolated session:

ness --worktree feature-x

Full CLI reference: docs/cli.md · Configuration: docs/configuration.md

Quick start — SDK

import asyncio
from langchain_core.tools import tool
from ness_agent import NessAgent, PromptLayers, PromptLayersConfig

@tool
def ping() -> str:
    """Return pong."""
    return "pong"

async def main() -> None:
    agent = NessAgent(
        model=your_chat_model,
        tools=[ping],
        prompt=PromptLayers(PromptLayersConfig(l0="You are a helpful agent.", persona="Be concise.")),
    )
    session = agent.session(thread_id="demo-1")
    result = await session.run("say hello")
    print(result.assistant_message)

asyncio.run(main())

Full SDK guide: docs/sdk.md · Architecture: docs/architecture.md

Documentation

Contributing

Contributions welcome. See CONTRIBUTING.md for dev setup and PR guidelines.

License

Licensed under the Apache License 2.0. See LICENSE.