npm package: @gustavjorlov/agent
Description: > Quick Start (no clone required) > > 1. Run the agent immediately: >    ``` >    npx @gustavjorlov/agent >    ``` > 2. When prompted (or if it errors about a missing key), create a user config: >    ``` >    npx @gustavjorlov/agent init >    ``` > 3. Ope
Latest version: 0.4.0

# Code Editing Agent (TypeScript)

> Quick Start (no clone required)
>
> 1. Run the agent immediately:
>    ```
>    npx @gustavjorlov/agent
>    ```
> 2. When prompted (or if it errors about a missing key), create a user config:
>    ```
>    npx @gustavjorlov/agent init
>    ```
> 3. Open the created file `~/.config/agent/config.env` (on macOS/Linux) and add your Anthropic API key:
>    ```
>    ANTHROPIC_API_KEY=sk-your-key
>    MODEL=claude-3-7-sonnet-20250219
>    MAX_TOKENS=1024
>    ```
>    (On Windows the directory is usually `%APPDATA%/agent/config.env`.)
> 4. Re-run:
>    ```
>    npx @gustavjorlov/agent
>    ```
> 5. Optional: show help / sources:
>    ```
>    npx @gustavjorlov/agent --help
>    npx @gustavjorlov/agent --verbose
>    ```
>
> You only need to set the key once; future runs will pick it up automatically.

Coding agent that doesn't stop and ask for permissions, it goes on until the task is done 😎

Implements:
- Chat loop with Claude
- Tool definitions sent via Messages API
- Twelve tools:
  - File Operations:
    - `read_file`: Read the contents of a specified file
    - `list_files`: List files and directories at a given path
    - `edit_file`: Make edits to a text file via string replacement
    - `create_file`: Create a new text file with provided content
  - Web & System:
    - `url_fetch`: Fetch the contents of a URL (HTTP/HTTPS) and return raw text/HTML (10s timeout)
    - `run_shell_command`: Execute whitelisted shell commands
  - Git Version Control:
    - `git_add`: Add file(s) to the git staging area
    - `git_commit`: Commit staged changes with a message
    - `git_status`: Show working tree status
    - `git_log`: Show commit history
    - `git_branch`: List, create, or checkout branches
    - `git_merge`: Merge a branch into the current branch
    - `git_pull`: Pull latest changes from a remote

## Dev Setup

1. Install dependencies:

```
npm install
```

2. Copy env file and set your key:

```
cp .env.example .env
# edit .env and set ANTHROPIC_API_KEY
```

3. Run in dev mode (TypeScript directly):

```
npm run dev
```

4. Or build & run:

```
npm run build
npm start
```

## Usage
Type your prompts. The agent will call tools automatically and print tool invocations.

Examples:
- "What do you see in this directory?"
- "Create fizzbuzz.js that prints FizzBuzz to 100"
- "Edit fizzbuzz.js so it only prints to 15"
- "Fetch the HTML from example.com and summarize it"
- "Create a new directory called 'examples' with a README file"
- Git Operations:
  - "Show me the git status and explain what's changed"
  - "Add all files and commit with a message 'Initial implementation'"
  - "Create a new feature branch and switch to it"
  - "Show me the recent commit history"
  - "Merge the feature branch into main"

## Notes
- Minimal JSON schema translation from Zod (enough for the demo)
- Tool execution results are returned as `tool_result` blocks
- `edit_file` uses simple string replacement mirroring the article's approach
- `run_shell_command` only allows whitelisted commands (ls, cat, echo, grep, head, tail, node, tsc, npm, npx, git, touch)
- `url_fetch` fetches raw HTML/text from URLs with a 10-second timeout
- `create_file` can overwrite existing files when the overwrite flag is set to true

## Future Enhancements
- Add streaming output
- Add richer JSON schema generation
- Expand test coverage for all tools
- Add more whitelisted shell commands
- Implement rate limiting for web requests
- Support binary file handling

## Roadmap / Phases

This section outlines upcoming structured phases. (Numbering starts at the next significant feature batch.)

### Phase 3: Session Management & Listing
Goal: Introduce `agent session list` / future resume capabilities. Prerequisite: centralize session storage.

#### Prerequisite: Centralize Session JSON Storage
Currently session snapshots are written to a per-project hidden directory: `./.agent/session-*.json`.
We will migrate to a unified user-level storage alongside config (e.g. `~/.config/agent` on macOS/Linux, `%APPDATA%/agent` on Windows) while still keeping sessions segregated per original working directory.

Structure (proposed):
```
~/.config/agent/
  config.env
  sessions/
    projects/
      <project-slug>/
        meta.json            # { cwd, slug, hash, createdAt, updatedAt, migrated }
        session-YYYYMMDD-HHMMSS.json
```

Project slug derivation:
1. Resolve absolute path of the CWD when the agent starts.
2. Compute `hash = sha256(realpath).hex.slice(0,10)`.
3. Sanitize `basename(realpath)` → lowercase alphanumerics + `-`.
4. Slug format: `<sanitized-basename>-<hash>` (ensures uniqueness even for folders with same name).

Rationale:
- Enables global listing across projects without scanning the whole filesystem.
- Avoids leaking full paths in directory names (privacy) while still being human friendly.
- Stable & deterministic for resume / indexing.

Environment override (optional):
- `AGENT_SESSION_DIR` → if set, supersedes default `sessions/` root (useful for testing).

API / Code Changes (planned):
1. Add util `getSessionProjectDir(cwd)` in a new `sessionStore.ts`.
2. Replace `createSessionLogger` in `agent.ts` to write into project dir; create if missing.
3. Write / update `meta.json` on first session write or when `cwd` changes.
4. (Optional early) Maintain a lightweight project-level `index.json` summarizing sessions (id, createdAt, file path) to speed up listing.
5. Add migration routine: if `./.agent/session-*.json` exists and target project dir is empty, copy files over, set `migrated: true` in `meta.json`, optionally leave originals (first release) then remove in later version.

Session File Naming (unchanged):
`session-YYYYMMDD-HHMMSS.json` (keeps chronological sorting). Potential later enhancement: append incremental counter if multiple in same second.

Edge Cases Considered:
- Permissions: ensure `sessions/projects/<slug>` is `0700` (POSIX) if created; warn if broader.
- Concurrency: if multiple agent processes start simultaneously, create dir with `recursive: true`; writing distinct filenames avoids collisions. (Future: file locking for index maintenance.)
- Very large number of sessions: listing will first read filenames; only parse `meta.json` + maybe first N session files for summary.
- Path changes (project moved): if `cwd` hash differs, a new slug is created; old slug remains intact (explicit resume may later allow re-link).

Listing Command (Phase 3 proper):
- `agent session list` (future) will enumerate `sessions/projects/*/*session-*.json`, building a table: Project Name, Sessions, Last Activity, Path (from meta.json `cwd`).
- Filtering by current project: only show sessions whose `meta.json.cwd` matches the resolved current path hash.

Migration Strategy:
1. Ship code that writes ONLY to new location but also (temporarily) copies to legacy `./.agent` for one minor version (optional) OR
2. On start, detect legacy sessions → migrate forward → print one-line notice with count migrated.
Chosen approach: forward migration on demand (no dual writes) to keep logic simple.

Telemetry / Privacy (future consideration):
- No extra data beyond existing messages; meta only stores original absolute `cwd` for local listing (never transmitted externally).

Completion Criteria for Prerequisite:
- New sessions appear under user config dir with correct project slug.
- Running agent twice in same directory appends new session files to same slug.
- Legacy `./.agent` no longer receives new writes (post-migration).
- README updated; warning printed once if legacy sessions migrated.

After this prerequisite is merged, implement the `agent session list` command to consume the new structure.

Runtime note: On first run after upgrading, if legacy `./.agent/session-*.json` files are detected they will be migrated automatically to the centralized store with a one-line notice. New sessions are no longer written to the project-local `.agent` folder.

## CLI (npx) Usage
This project can be invoked directly without cloning once published:

```
npx @gustavjorlov/agent --help
```

### Configuration Locations (precedence highest last)
1. Legacy project `.env` (deprecated – warning emitted)
2. User config directory: `~/.config/agent/config.env` or `config.json`
3. Local `.agent.env`
4. `AGENT_CONFIG` environment variable pointing to a file
5. `--config /path/to/file` (highest)

Create a user config quickly:
```
npx @gustavjorlov/agent init
```
Then edit `~/.config/agent/config.env`:
```
ANTHROPIC_API_KEY=sk-your-key
MODEL=claude-3-7-sonnet-20250219
MAX_TOKENS=1024
```

Run the chat:
```
npx @gustavjorlov/agent
```

Override model ad-hoc:
```
npx @gustavjorlov/agent --config ./my-session.env
```

The binary name when linked locally is `agent` (e.g. after `npm link`).

Deprecated notice: Root `.env` support will be removed after version 0.3.0. Migrate to `~/.config/agent/config.env`, `.agent.env`, or use `--config`.